diff options
Diffstat (limited to 'doc/html')
146 files changed, 10656 insertions, 9764 deletions
diff --git a/doc/html/Ada95.html b/doc/html/Ada95.html index 1affa3fbbab5..49c9899a5384 100644 --- a/doc/html/Ada95.html +++ b/doc/html/Ada95.html @@ -1,7 +1,7 @@ <!-- - $Id: Ada95.html,v 1.18 2022/03/05 16:09:29 tom Exp $ + $Id: Ada95.html,v 1.20 2025/07/13 09:08:38 tom Exp $ **************************************************************************** - * Copyright 2019-2021,2022 Thomas E. Dickey * + * Copyright 2019-2022,2025 Thomas E. Dickey * * Copyright 2000-2010,2013 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -57,7 +57,7 @@ ncurses package, a clone of the SVr4 curses model.<br> I did the development on an Intel box running the latest stable release of <a href="http://www.linux.org">Linux</a>, ncurses - and the most recent released <a href="https://ftp.gnu.org/gnu/gcc/">GNU + and the most recent released <a href="https://ftp.gnu.org/gnu/gcc/">GNU Ada Translator</a> gnat versions. For any older versions of ncurses and gnat it is not guaranteed to work.</li> diff --git a/doc/html/NCURSES-Programming-HOWTO.html b/doc/html/NCURSES-Programming-HOWTO.html index 9a3f078d2f1c..47a813df1ec8 100644 --- a/doc/html/NCURSES-Programming-HOWTO.html +++ b/doc/html/NCURSES-Programming-HOWTO.html @@ -3,7 +3,7 @@ <html> <head> <meta name="generator" content= - "HTML Tidy for HTML5 for Linux version 5.6.0"> + "HTML Tidy for HTML5 for Linux version 5.8.0"> <title>NCURSES Programming HOWTO</title> <meta name="GENERATOR" content= "Modular DocBook HTML Stylesheet Version 1.79"> @@ -15,21 +15,35 @@ <h1 class="TITLE"><a name="AEN2" id="AEN2">NCURSES Programming HOWTO</a></h1> - <h3 class="AUTHOR"><a name="AEN4" id="AEN4">Pradeep - Padala</a></h3> + <div class="AUTHORGROUP"> + <a name="AEN4" id="AEN4"></a> + <h3 class="AUTHOR"><a name="AEN5" id="AEN5">Pradeep + Padala</a></h3> - <div class="AFFILIATION"> - <div class="ADDRESS"> - <p class="ADDRESS"><code class="EMAIL"><<a href= - "mailto:ppadala@gmail.com">ppadala@gmail.com</a>></code> - </p> + <div class="AFFILIATION"> + <div class="ADDRESS"> + <p class="ADDRESS"><code class="EMAIL"><<a href= + "mailto:ppadala@gmail.com">ppadala@gmail.com</a>></code> + </p> + </div> + </div> + + <h3 class="AUTHOR"><a name="AEN11" id="AEN11">Thomas E. + Dickey</a></h3> + + <div class="AFFILIATION"> + <div class="ADDRESS"> + <p class="ADDRESS"><code class="EMAIL"><<a href= + "mailto:dickey@invisible-island.net">dickey@invisible-island.net</a>></code> + </p> + </div> </div> </div> - <p class="PUBDATE">v1.9, 2005-06-20<br></p> + <p class="PUBDATE">v2.1, 2024-09-08<br></p> <div class="REVHISTORY"> - <table width="100%" border="0" summary="revisions"> + <table width="100%" border="0"> <tr> <th align="left" valign="top" colspan="3"><b>Revision History</b> @@ -37,6 +51,18 @@ </tr> <tr> + <td align="left">Revision 2.1</td> + <td align="left">2024-09-08</td> + <td align="left">Revised by: dickey</td> + </tr> + + <tr> + <td align="left" colspan="3">Fixes for the sample + programs. Remove obsolete mailing addresses. Update + publication date.</td> + </tr> + + <tr> <td align="left">Revision 2.0</td> <td align="left">2022-12-03</td> <td align="left">Revised by: dickey</td> @@ -179,14 +205,14 @@ <div> <div class="ABSTRACT"> - <a name="AEN72" id="AEN72"></a> + <a name="AEN85" id="AEN85"></a> <p><span class="emphasis"><i class="EMPHASIS">This document is intended to be an "All in One" guide for programming with ncurses and its sister libraries. We graduate from a simple "Hello World" program to more complex form manipulation. No prior experience in ncurses is assumed. Send comments to <a href= - "mailto:ppadala@gmail.com" target="_top">this + "mailto:bug-ncurses@gnu.org" target="_top">this address</a></i></span> </p> </div> @@ -223,8 +249,8 @@ <dd> <dl> - <dt>1.6.1. <a href="#LISTFORMATS">Readily available - formats from tldp.org</a></dt> + <dt>1.6.1. <a href="#LISTFORMATS">Alternative + formats</a></dt> <dt>1.6.2. <a href="#BUILDSOURCE">Building from source</a></dt> @@ -299,7 +325,7 @@ <dt>6.1. <a href="#ADDCHCLASS">addch() class of functions</a></dt> - <dt>6.2. <a href="#AEN303">mvaddch(), waddch() and + <dt>6.2. <a href="#AEN324">mvaddch(), waddch() and mvwaddch()</a></dt> <dt>6.3. <a href="#PRINTWCLASS">printw() class of @@ -658,7 +684,7 @@ of bytes. All the capabilities (such as moving the cursor to a new location, erasing part of the screen, scrolling the screen, changing modes, etc.) of terminals could be accessed - through these series of bytes. These control seeuqnces are + through these series of bytes. These control sequences are usually called escape sequences, because they start with an escape(0x1B) character. Even today, with proper emulation, we can send escape sequences to the emulator and achieve the @@ -767,36 +793,41 @@ package</i></span> </p> - <p>NCURSES can be obtained from <a href= - "ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz" target= - "_top">ftp://ftp.gnu.org/pub/gnu/ncurses/ncurses.tar.gz</a> - or any of the ftp sites mentioned in <a href= - "https://www.gnu.org/order/ftp.html" target= - "_top">https://www.gnu.org/order/ftp.html</a>.</p> + <p>NCURSES can be obtained from</p> - <p>Read the README and INSTALL files for details on to how - to install it. It usually involves the following - operations.</p> + <ul> + <li> + <p>the home page at <a href= + "https://invisible-island.net/" target= + "_top">https://invisible-island.net</a>, as well as</p> + </li> - <pre class= - "PROGRAMLISTING"> tar zxvf ncurses<version>.tar.gz # unzip and untar the archive - cd ncurses<version> # cd to the directory - ./configure # configure the build according to your - # environment - make # make it - su root # become root - make install # install it</pre> - <p><span class="emphasis"><i class="EMPHASIS">Using the - RPM</i></span> - </p> + <li> + <p><a href="https://ftp.gnu.org/pub/gnu/ncurses/" + target="_top">https://ftp.gnu.org/pub/gnu/ncurses/</a> + or</p> + </li> + + <li> + <p>any of the mirror sites mentioned in <a href= + "https://www.gnu.org/order/ftp.html" target= + "_top">https://www.gnu.org/order/ftp.html</a>.</p> + </li> + </ul> - <p>NCURSES RPM can be found and downloaded from <a href= - "https://rpmfind.net" target="_top">https://rpmfind.net</a> - . The RPM can be installed with the following command after - becoming root.</p> + <p>Read the README and <a href= + "https://invisible-island.net/ncurses/INSTALL.html" target= + "_top">INSTALL</a> files for details on to how to install + it. It usually involves the following operations.</p> <pre class= - "PROGRAMLISTING"> rpm -i <downloaded rpm></pre> + "PROGRAMLISTING"> tar zxvf ncurses<version>.tar.gz # unzip and untar the archive + cd ncurses<version> # cd to the directory + ./configure # configure the build according to your + # environment + make # make it + su root # become root + make install # install it</pre> </div> <div class="SECT2"> @@ -819,10 +850,10 @@ <h3 class="SECT2"><a name="ABOUTPROGRAMS" id= "ABOUTPROGRAMS">1.5. About the Programs</a></h3> - <p>All the programs in the document are available in zipped - form <a href= - "https://www.tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs.tar.gz" - target="_top">here</a>. Unzip and untar it. The directory + <p>All the programs in the document are available in + gzipped form <a href= + "https://invisible-island.net/ncurses/howto/ncurses_programs.tar.gz" + target="_top">here</a>. Ungzip and untar it. The directory structure looks like this.</p> <pre class="PROGRAMLISTING">ncurses @@ -850,7 +881,7 @@ JustForFun | |----> hanoi.c -- The Towers of Hanoi Solver |----> life.c -- The Game of Life demo - |----> magic.c -- An Odd Order Magic Square builder + |----> magic.c -- An Odd Order Magic Square builder |----> queens.c -- The famous N-Queens Solver |----> shuffle.c -- A fun game, if you have time to kill |----> tt.c -- A very trivial typing tutor @@ -866,23 +897,23 @@ JustForFun | -- rt from box() |----> printw_example.c -- A very simple printw() example |----> scanw_example.c -- A very simple getstr() example - |----> simple_attr.c -- A program that can print a c file with + |----> simple_attr.c -- A program that can print a c file with | -- comments in attribute |----> simple_color.c -- A simple example demonstrating colors - |----> simple_key.c -- A menu accessible with keyboard UP, DOWN + |----> simple_key.c -- A menu accessible with keyboard UP, DOWN | -- arrows |----> temp_leave.c -- Demonstrates temporarily leaving curses mode |----> win_border.c -- Shows Creation of windows and borders |----> with_chgat.c -- chgat() usage example - forms + forms | |----> form_attrib.c -- Usage of field attributes |----> form_options.c -- Usage of field options |----> form_simple.c -- A simple form example |----> form_win.c -- Demo of windows associated with forms - menus + menus | |----> menu_attrib.c -- Usage of menu attributes |----> menu_item_data.c -- Usage of item_name(), etc. functions @@ -894,9 +925,9 @@ JustForFun |----> menu_userptr.c -- Usage of user pointer |----> menu_win.c -- Demo of windows associated with menus - panels + panels | - |----> panel_browse.c -- Panel browsing through tab. Usage of user + |----> panel_browse.c -- Panel browsing through tab. Usage of user | -- pointer |----> panel_hide.c -- Hiding and Un hiding of panels |----> panel_resize.c -- Moving and resizing of panels @@ -914,12 +945,6 @@ JustForFun <p>For every example, I have included path name for the file relative to the examples directory.</p> - <p>If you prefer browsing individual programs, point your - browser to <a href= - "https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/" - target= - "_top">https://tldp.org/HOWTO/NCURSES-Programming-HOWTO/ncurses_programs/</a></p> - <p>All the programs are released under the same license that is used by ncurses (MIT-style). This gives you the ability to do pretty much anything other than claiming them @@ -933,40 +958,38 @@ JustForFun <h3 class="SECT2"><a name="OTHERFORMATS" id= "OTHERFORMATS">1.6. Other Formats of the document</a></h3> - <p>This howto is also available in various other formats on - the tldp.org site. Here are the links to other formats of - this document.</p> + <p>This howto is also available in other formats. Here are + the links to other formats of this document.</p> <div class="SECT3"> <hr> <h4 class="SECT3"><a name="LISTFORMATS" id= - "LISTFORMATS">1.6.1. Readily available formats from - tldp.org</a></h4> + "LISTFORMATS">1.6.1. Alternative formats</a></h4> <ul> <li> <p><a href= - "https://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/pdf/NCURSES-Programming-HOWTO.pdf" + "https://invisible-island.net/ncurses/howto/NCURSES-Programming-HOWTO.pdf" target="_top">Acrobat PDF Format</a></p> </li> <li> <p><a href= - "https://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/ps/NCURSES-Programming-HOWTO.ps.gz" + "https://invisible-island.net/ncurses/howto/NCURSES-Programming-HOWTO.ps" target="_top">PostScript Format</a></p> </li> <li> <p><a href= - "https://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html/NCURSES-Programming-HOWTO-html.tar.gz" + "https://invisible-island.net/ncurses/howto/NCURSES-Programming-HOWTO-html.tar.gz" target="_top">In Multiple HTML pages</a></p> </li> <li> <p><a href= - "https://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/NCURSES-Programming-HOWTO.html" - target="_top">In One big HTML format</a></p> + "https://invisible-island.net/ncurses/howto/NCURSES-Programming-HOWTO.html" + target="_top">A single HTML file.</a></p> </li> </ul> </div> @@ -977,37 +1000,29 @@ JustForFun <h4 class="SECT3"><a name="BUILDSOURCE" id= "BUILDSOURCE">1.6.2. Building from source</a></h4> - <p>If above links are broken or if you want to experiment - with sgml read on.</p> + <p>The sources for this HOWTO can be retrieved from</p> - <pre class= - "PROGRAMLISTING"> Get both the source and the tar,gzipped programs, available at - http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/ - NCURSES-HOWTO/NCURSES-Programming-HOWTO.sgml - http://cvsview.tldp.org/index.cgi/LDP/howto/docbook/ - NCURSES-HOWTO/ncurses_programs.tar.gz - - Unzip ncurses_programs.tar.gz with - tar zxvf ncurses_programs.tar.gz - - Use jade to create various formats. For example if you just want to create - the multiple html files, you would use - jade -t sgml -i html -d <path to docbook html stylesheet> - NCURSES-Programming-HOWTO.sgml - to get pdf, first create a single html file of the HOWTO with - jade -t sgml -i html -d <path to docbook html stylesheet> -V nochunks - NCURSES-Programming-HOWTO.sgml > NCURSES-ONE-BIG-FILE.html - then use htmldoc to get pdf file with - htmldoc --size universal -t pdf --firstpage p1 -f <output file name.pdf> - NCURSES-ONE-BIG-FILE.html - for ps, you would use - htmldoc --size universal -t ps --firstpage p1 -f <output file name.ps> - NCURSES-ONE-BIG-FILE.html</pre> - <p>See <a href= - "https://www.tldp.org/LDP/LDP-Author-Guide/" target= - "_top">LDP Author guide</a> for more details. If all else - fails, mail me at <a href="ppadala@gmail.com" target= - "_top">ppadala@gmail.com</a></p> + <div class="INFORMALEXAMPLE"> + <a name="AEN164" id="AEN164"></a> + + <pre class="PROGRAMLISTING"><a href= + "https://github.com/ThomasDickey/ncurses-howto-snapshots" + target= + "_top">https://github.com/ThomasDickey/ncurses-howto-snapshots</a></pre> + </div> + + <p>These tools were used to format the HOWTO and build + the examples:</p> + + <ul> + <li> + <p>docbook-utils (a Debian package)</p> + </li> + + <li> + <p>gcc</p> + </li> + </ul> </div> </div> @@ -1017,21 +1032,22 @@ JustForFun <h3 class="SECT2"><a name="CREDITS" id="CREDITS">1.7. Credits</a></h3> - <p>I thank <a href="mailto:sharath_1@usa.net" target= - "_top">Sharath</a> and Emre Akbas for helping me with few - sections. The introduction was initially written by - sharath. I rewrote it with few excerpts taken from his - initial work. Emre helped in writing printw and scanw - sections.</p> - - <p>Perl equivalents of the example programs are contributed - by <a href="mailto:Aratnaweera@virtusa.com" target= - "_top">Anuradha Ratnaweera</a>.</p> - - <p>Then comes <a href="mailto:parimi@ece.arizona.edu" - target="_top">Ravi Parimi</a>, my dearest friend, who has - been on this project before even one line was written. He - constantly bombarded me with suggestions and patiently + <p>I thank <span class="emphasis"><i class= + "EMPHASIS">Sharath</i></span> and <span class= + "emphasis"><i class="EMPHASIS">Emre Akbas</i></span> for + helping me with few sections. The introduction was + initially written by Sharath. I rewrote it with few + excerpts taken from his initial work. Emre helped in + writing printw and scanw sections.</p> + + <p>Perl equivalents of the example programs were + contributed by <span class="emphasis"><i class= + "EMPHASIS">Anuradha Ratnaweera</i></span>.</p> + + <p>Then comes <span class="emphasis"><i class= + "EMPHASIS">Ravi Parimi</i></span>, my dearest friend, who + has been on this project before even one line was written. + He constantly bombarded me with suggestions and patiently reviewed the whole text. He also checked each program on Linux and Solaris.</p> </div> @@ -1150,15 +1166,16 @@ JustForFun <pre class="PROGRAMLISTING"><span class= "INLINEMEDIAOBJECT">#include <curses.h> -int main() -{ - initscr(); /* Start curses mode */ - printw("Hello World !!!"); /* Print Hello World */ - refresh(); /* Print it on to the real screen */ - getch(); /* Wait for user input */ - endwin(); /* End curses mode */ +int +main(void) +{ + initscr(); /* Start curses mode */ + printw("Hello World !!!"); /* Print Hello World */ + refresh(); /* Print it on to the real screen */ + getch(); /* Wait for user input */ + endwin(); /* End curses mode */ - return 0; + return 0; }</span></pre> </div> </div> @@ -1388,34 +1405,36 @@ int main() <pre class="PROGRAMLISTING"><span class= "INLINEMEDIAOBJECT">#include <curses.h> -int main() -{ int ch; - - initscr(); /* Start curses mode */ - raw(); /* Line buffering disabled */ - keypad(stdscr, TRUE); /* We get F1, F2 etc.. */ - noecho(); /* Don't echo() while we do getch */ - - printw("Type any character to see it in bold\n"); - ch = getch(); /* If raw() hadn't been called - * we have to press enter before it - * gets to the program */ - if(ch == KEY_F(1)) /* Without keypad enabled this will */ - printw("F1 Key pressed");/* not get to us either */ - /* Without noecho() some ugly escape - * characters might have been printed - * on screen */ - else - { printw("The pressed key is "); - attron(A_BOLD); - printw("%c", ch); - attroff(A_BOLD); - } - refresh(); /* Print it on to the real screen */ - getch(); /* Wait for user input */ - endwin(); /* End curses mode */ +int +main(void) +{ + int ch; + + initscr(); /* Start curses mode */ + raw(); /* Line buffering disabled */ + keypad(stdscr, TRUE); /* We get F1, F2 etc.. */ + noecho(); /* Don't echo() while we do getch */ + + printw("Type any character to see it in bold\n"); + ch = getch(); /* If raw() hadn't been called + * we have to press enter before it + * gets to the program */ + if (ch == KEY_F(1)) /* Without keypad enabled this will */ + printw("F1 Key pressed"); /* not get to us either */ + /* Without noecho() some ugly escape + * characters might have been printed + * on screen */ + else { + printw("The pressed key is "); + attron(A_BOLD); + printw("%c", ch); + attroff(A_BOLD); + } + refresh(); /* Print it on to the real screen */ + getch(); /* Wait for user input */ + endwin(); /* End curses mode */ - return 0; + return 0; }</span></pre> </div> @@ -1573,7 +1592,7 @@ int main() <div class="SECT2"> <hr> - <h3 class="SECT2"><a name="AEN303" id="AEN303">6.2. + <h3 class="SECT2"><a name="AEN324" id="AEN324">6.2. mvaddch(), waddch() and mvwaddch()</a></h3> <p><tt class="LITERAL">mvaddch()</tt> is used to move the @@ -1669,24 +1688,25 @@ int main() <pre class="PROGRAMLISTING"><span class= "INLINEMEDIAOBJECT">#include <curses.h> -#include <string.h> - -int main() +#include <string.h> + +int +main(void) { - char mesg[]="Just a string"; /* message to be appeared on the screen */ - int row,col; /* to store the number of rows and * - * the number of columns of the screen */ - initscr(); /* start the curses mode */ - getmaxyx(stdscr,row,col); /* get the number of rows and columns */ - mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg); - /* print the message at the center of the screen */ - mvprintw(row-2,0,"This screen has %d rows and %d columns\n",row,col); - printw("Try resizing your window(if possible) and then run this program again"); - refresh(); - getch(); - endwin(); - - return 0; + char mesg[] = "Just a string"; /* message to be appeared on the screen */ + int row, col; /* to store the number of rows and * + * the number of columns of the screen */ + initscr(); /* start the curses mode */ + getmaxyx(stdscr, row, col); /* get the number of rows and columns */ + mvprintw(row / 2, (col - (int) strlen(mesg)) / 2, "%s", mesg); + /* print the message at the center of the screen */ + mvprintw(row - 2, 0, "This screen has %d rows and %d columns\n", row, col); + printw("Try resizing your window(if possible) and then run this program again"); + refresh(); + getch(); + endwin(); + + return 0; }</span></pre> </div> @@ -1865,24 +1885,25 @@ int main() <pre class="PROGRAMLISTING"><span class= "INLINEMEDIAOBJECT">#include <curses.h> -#include <string.h> - -int main() +#include <string.h> + +int +main(void) { - char mesg[]="Enter a string: "; /* message to be appeared on the screen */ - char str[80]; - int row,col; /* to store the number of rows and * - * the number of columns of the screen */ - initscr(); /* start the curses mode */ - getmaxyx(stdscr,row,col); /* get the number of rows and columns */ - mvprintw(row/2,(col-strlen(mesg))/2,"%s",mesg); - /* print the message at the center of the screen */ - getstr(str); - mvprintw(LINES - 2, 0, "You Entered: %s", str); - getch(); - endwin(); - - return 0; + char mesg[] = "Enter a string: "; /* message to be appeared on the screen */ + char str[80]; + int row, col; /* to store the number of rows and * + * the number of columns of the screen */ + initscr(); /* start the curses mode */ + getmaxyx(stdscr, row, col); /* get the number of rows and columns */ + mvprintw(row / 2, (col - (int) strlen(mesg)) / 2, "%s", mesg); + /* print the message at the center of the screen */ + getstr(str); + mvprintw(LINES - 2, 0, "You Entered: %s", str); + getch(); + endwin(); + + return 0; }</span></pre> </div> </div> @@ -1911,55 +1932,54 @@ int main() #include <curses.h> #include <stdlib.h> -int main(int argc, char *argv[]) -{ - int ch, prev, row, col; - prev = EOF; - FILE *fp; - int y, x; - - if(argc != 2) - { - printf("Usage: %s <a c file name>\n", argv[0]); - exit(1); - } - fp = fopen(argv[1], "r"); - if(fp == NULL) - { - perror("Cannot open input file"); - exit(1); - } - initscr(); /* Start curses mode */ - getmaxyx(stdscr, row, col); /* find the boundaries of the screeen */ - while((ch = fgetc(fp)) != EOF) /* read the file till we reach the end */ - { - getyx(stdscr, y, x); /* get the current cursor position */ - if(y == (row - 1)) /* are we are at the end of the screen */ - { - printw("<-Press Any Key->"); /* tell the user to press a key */ - getch(); - clear(); /* clear the screen */ - move(0, 0); /* start at the beginning of the screen */ +int +main(int argc, char *argv[]) +{ + int ch, row, col; + int prev = EOF; + FILE *fp; + int y, x; + + if (argc != 2) { + printf("Usage: %s <a c file name>\n", argv[0]); + exit(1); } - if(prev == '/' && ch == '*') /* If it is / and * then only - * switch bold on */ + fp = fopen(argv[1], "r"); + if (fp == NULL) { + perror("Cannot open input file"); + exit(1); + } + initscr(); /* Start curses mode */ + getmaxyx(stdscr, row, col); /* find the boundaries of the screeen */ + (void) col; + while ((ch = fgetc(fp)) != EOF) /* read the file till we reach the end */ { - attron(A_BOLD); /* cut bold on */ - getyx(stdscr, y, x); /* get the current cursor position */ - move(y, x - 1); /* back up one space */ - printw("%c%c", '/', ch); /* The actual printing is done here */ + getyx(stdscr, y, x); /* get the current cursor position */ + if (y == (row - 1)) /* are we are at the end of the screen */ + { + printw("<-Press Any Key->"); /* tell the user to press a key */ + getch(); + clear(); /* clear the screen */ + move(0, 0); /* start at the beginning of the screen */ + } + if (prev == '/' && ch == '*') /* If it is / and * then only + * switch bold on */ + { + attron(A_BOLD); /* cut bold on */ + getyx(stdscr, y, x); /* get the current cursor position */ + move(y, x - 1); /* back up one space */ + printw("%c%c", '/', ch); /* The actual printing is done here */ + } else + printw("%c", ch); + refresh(); + if (prev == '*' && ch == '/') + attroff(A_BOLD); /* Switch it off once we got * + * and then / */ + prev = ch; } - else - printw("%c", ch); - refresh(); - if(prev == '*' && ch == '/') - attroff(A_BOLD); /* Switch it off once we got * - * and then / */ - prev = ch; - } - endwin(); /* End curses mode */ - fclose(fp); - return 0; + endwin(); /* End curses mode */ + fclose(fp); + return 0; }</span></pre> </div> @@ -2002,8 +2022,8 @@ int main(int argc, char *argv[]) following video attributes, which are defined in <curses.h> can be passed to these functions.</p> - <pre class="PROGRAMLISTING"> - A_NORMAL Normal display (no highlight) + <pre class= + "PROGRAMLISTING"> A_NORMAL Normal display (no highlight) A_STANDOUT Best highlighting mode of the terminal. A_UNDERLINE Underlining A_REVERSE Reverse video @@ -2014,10 +2034,9 @@ int main(int argc, char *argv[]) A_INVIS Invisible or blank mode A_ALTCHARSET Alternate character set A_CHARTEXT Bit-mask to extract a character - COLOR_PAIR(n) Color-pair number n - </pre> + COLOR_PAIR(n) Color-pair number n </pre> <p>The last one is the most colorful one :-) Colors are - explained in the <a href="#color" target="_top">next + explained in the <a href="#COLOR" target="_top">next sections</a>.</p> <p>We can OR(|) any number of above attributes to get a @@ -2129,27 +2148,29 @@ int main(int argc, char *argv[]) <pre class="PROGRAMLISTING"><span class= "INLINEMEDIAOBJECT">#include <curses.h> -int main(int argc, char *argv[]) -{ initscr(); /* Start curses mode */ - start_color(); /* Start color functionality */ - - init_pair(1, COLOR_CYAN, COLOR_BLACK); - printw("A Big string which i didn't care to type fully "); - mvchgat(0, 0, -1, A_BLINK, 1, NULL); - /* - * First two parameters specify the position at which to start - * Third parameter number of characters to update. -1 means till - * end of line - * Forth parameter is the normal attribute you wanted to give - * to the character - * Fifth is the color index. It is the index given during init_pair() - * use 0 if you didn't want color - * Sixth one is always NULL - */ - refresh(); - getch(); - endwin(); /* End curses mode */ - return 0; +int +main(void) +{ + initscr(); /* Start curses mode */ + start_color(); /* Start color functionality */ + + init_pair(1, COLOR_CYAN, COLOR_BLACK); + printw("A Big string which i didn't care to type fully "); + mvchgat(0, 0, -1, A_BLINK, 1, NULL); + /* + * First two parameters specify the position at which to start + * Third parameter number of characters to update. -1 means till + * end of line + * Forth parameter is the normal attribute you wanted to give + * to the character + * Fifth is the color index. It is the index given during init_pair() + * use 0 if you didn't want color + * Sixth one is always NULL + */ + refresh(); + getch(); + endwin(); /* End curses mode */ + return 0; }</span></pre> </div> @@ -2222,81 +2243,86 @@ int main(int argc, char *argv[]) WINDOW *create_newwin(int height, int width, int starty, int startx); void destroy_win(WINDOW *local_win); -int main(int argc, char *argv[]) -{ WINDOW *my_win; - int startx, starty, width, height; - int ch; - - initscr(); /* Start curses mode */ - cbreak(); /* Line buffering disabled, Pass on - * everty thing to me */ - keypad(stdscr, TRUE); /* I need that nifty F1 */ - - height = 3; - width = 10; - starty = (LINES - height) / 2; /* Calculating for a center placement */ - startx = (COLS - width) / 2; /* of the window */ - printw("Press F1 to exit"); - refresh(); - my_win = create_newwin(height, width, starty, startx); - - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case KEY_LEFT: - destroy_win(my_win); - my_win = create_newwin(height, width, starty,--startx); - break; - case KEY_RIGHT: - destroy_win(my_win); - my_win = create_newwin(height, width, starty,++startx); - break; - case KEY_UP: - destroy_win(my_win); - my_win = create_newwin(height, width, --starty,startx); - break; - case KEY_DOWN: - destroy_win(my_win); - my_win = create_newwin(height, width, ++starty,startx); - break; - } +int +main(void) +{ + WINDOW *my_win; + int startx, starty, width, height; + int ch; + + initscr(); /* Start curses mode */ + cbreak(); /* Line buffering disabled, Pass on + * every thing to me */ + keypad(stdscr, TRUE); /* I need that nifty F1 */ + + height = 3; + width = 10; + starty = (LINES - height) / 2; /* Calculating for a center placement */ + startx = (COLS - width) / 2; /* of the window */ + printw("Press F1 to exit"); + refresh(); + my_win = create_newwin(height, width, starty, startx); + + while ((ch = getch()) != KEY_F(1)) { + switch (ch) { + case KEY_LEFT: + destroy_win(my_win); + my_win = create_newwin(height, width, starty, --startx); + break; + case KEY_RIGHT: + destroy_win(my_win); + my_win = create_newwin(height, width, starty, ++startx); + break; + case KEY_UP: + destroy_win(my_win); + my_win = create_newwin(height, width, --starty, startx); + break; + case KEY_DOWN: + destroy_win(my_win); + my_win = create_newwin(height, width, ++starty, startx); + break; } - - endwin(); /* End curses mode */ - return 0; + } + + endwin(); /* End curses mode */ + return 0; } -WINDOW *create_newwin(int height, int width, int starty, int startx) -{ WINDOW *local_win; +WINDOW * +create_newwin(int height, int width, int starty, int startx) +{ + WINDOW *local_win; - local_win = newwin(height, width, starty, startx); - box(local_win, 0 , 0); /* 0, 0 gives default characters - * for the vertical and horizontal - * lines */ - wrefresh(local_win); /* Show that box */ + local_win = newwin(height, width, starty, startx); + box(local_win, 0, 0); /* 0, 0 gives default characters + * for the vertical and horizontal + * lines */ + wrefresh(local_win); /* Show that box */ - return local_win; + return local_win; } -void destroy_win(WINDOW *local_win) -{ - /* box(local_win, ' ', ' '); : This won't produce the desired - * result of erasing the window. It will leave its four corners - * and so an ugly remnant of window. - */ - wborder(local_win, ' ', ' ', ' ',' ',' ',' ',' ',' '); - /* The parameters taken are - * 1. win: the window on which to operate - * 2. ls: character to be used for the left side of the window - * 3. rs: character to be used for the right side of the window - * 4. ts: character to be used for the top side of the window - * 5. bs: character to be used for the bottom side of the window - * 6. tl: character to be used for the top left corner of the window - * 7. tr: character to be used for the top right corner of the window - * 8. bl: character to be used for the bottom left corner of the window - * 9. br: character to be used for the bottom right corner of the window - */ - wrefresh(local_win); - delwin(local_win); +void +destroy_win(WINDOW *local_win) +{ + /* box(local_win, ' ', ' '); : This won't produce the desired + * result of erasing the window. It will leave its four corners + * and so an ugly remnant of window. + */ + wborder(local_win, ' ', ' ', ' ', ' ', ' ', ' ', ' ', ' '); + /* The parameters taken are + * 1. win: the window on which to operate + * 2. ls: character to be used for the left side of the window + * 3. rs: character to be used for the right side of the window + * 4. ts: character to be used for the top side of the window + * 5. bs: character to be used for the bottom side of the window + * 6. tl: character to be used for the top left corner of the window + * 7. tr: character to be used for the top right corner of the window + * 8. bl: character to be used for the bottom left corner of the window + * 9. br: character to be used for the bottom right corner of the window + */ + wrefresh(local_win); + delwin(local_win); }</span></pre> </div> </div> @@ -2391,122 +2417,129 @@ void destroy_win(WINDOW *local_win) "INLINEMEDIAOBJECT">#include <curses.h> typedef struct _win_border_struct { - chtype ls, rs, ts, bs, - tl, tr, bl, br; -}WIN_BORDER; + chtype ls, rs, ts, bs, tl, tr, bl, br; +} WIN_BORDER; typedef struct _WIN_struct { - int startx, starty; - int height, width; - WIN_BORDER border; -}WIN; - -void init_win_params(WIN *p_win); -void print_win_params(WIN *p_win); -void create_box(WIN *win, bool flag); - -int main(int argc, char *argv[]) -{ WIN win; - int ch; - - initscr(); /* Start curses mode */ - start_color(); /* Start the color functionality */ - cbreak(); /* Line buffering disabled, Pass on - * everty thing to me */ - keypad(stdscr, TRUE); /* I need that nifty F1 */ - noecho(); - init_pair(1, COLOR_CYAN, COLOR_BLACK); - - /* Initialize the window parameters */ - init_win_params(&win); - print_win_params(&win); - - attron(COLOR_PAIR(1)); - printw("Press F1 to exit"); - refresh(); - attroff(COLOR_PAIR(1)); - - create_box(&win, TRUE); - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case KEY_LEFT: - create_box(&win, FALSE); - --win.startx; - create_box(&win, TRUE); - break; - case KEY_RIGHT: - create_box(&win, FALSE); - ++win.startx; - create_box(&win, TRUE); - break; - case KEY_UP: - create_box(&win, FALSE); - --win.starty; - create_box(&win, TRUE); - break; - case KEY_DOWN: - create_box(&win, FALSE); - ++win.starty; - create_box(&win, TRUE); - break; - } + int startx, starty; + int height, width; + WIN_BORDER border; +} WIN; + +void init_win_params(WIN * p_win); +void print_win_params(WIN * p_win); +void create_box(WIN * win, bool flag); + +int +main(void) +{ + WIN win; + int ch; + + initscr(); /* Start curses mode */ + start_color(); /* Start the color functionality */ + cbreak(); /* Line buffering disabled, Pass on + * everty thing to me */ + keypad(stdscr, TRUE); /* I need that nifty F1 */ + noecho(); + init_pair(1, COLOR_CYAN, COLOR_BLACK); + + /* Initialize the window parameters */ + init_win_params(&win); + print_win_params(&win); + + attron(COLOR_PAIR(1)); + printw("Press F1 to exit"); + refresh(); + attroff(COLOR_PAIR(1)); + + create_box(&win, TRUE); + while ((ch = getch()) != KEY_F(1)) { + switch (ch) { + case KEY_LEFT: + create_box(&win, FALSE); + --win.startx; + create_box(&win, TRUE); + break; + case KEY_RIGHT: + create_box(&win, FALSE); + ++win.startx; + create_box(&win, TRUE); + break; + case KEY_UP: + create_box(&win, FALSE); + --win.starty; + create_box(&win, TRUE); + break; + case KEY_DOWN: + create_box(&win, FALSE); + ++win.starty; + create_box(&win, TRUE); + break; } - endwin(); /* End curses mode */ - return 0; + } + endwin(); /* End curses mode */ + return 0; } -void init_win_params(WIN *p_win) +void +init_win_params(WIN * p_win) { - p_win->height = 3; - p_win->width = 10; - p_win->starty = (LINES - p_win->height)/2; - p_win->startx = (COLS - p_win->width)/2; - - p_win->border.ls = '|'; - p_win->border.rs = '|'; - p_win->border.ts = '-'; - p_win->border.bs = '-'; - p_win->border.tl = '+'; - p_win->border.tr = '+'; - p_win->border.bl = '+'; - p_win->border.br = '+'; + p_win->height = 3; + p_win->width = 10; + p_win->starty = (LINES - p_win->height) / 2; + p_win->startx = (COLS - p_win->width) / 2; + + p_win->border.ls = '|'; + p_win->border.rs = '|'; + p_win->border.ts = '-'; + p_win->border.bs = '-'; + p_win->border.tl = '+'; + p_win->border.tr = '+'; + p_win->border.bl = '+'; + p_win->border.br = '+'; } -void print_win_params(WIN *p_win) + +void +print_win_params(WIN * p_win) { #ifdef _DEBUG - mvprintw(25, 0, "%d %d %d %d", p_win->startx, p_win->starty, - p_win->width, p_win->height); - refresh(); + mvprintw(25, 0, "%d %d %d %d", p_win->startx, p_win->starty, + p_win->width, p_win->height); + refresh(); +#else + (void) p_win; #endif } -void create_box(WIN *p_win, bool flag) -{ int i, j; - int x, y, w, h; - - x = p_win->startx; - y = p_win->starty; - w = p_win->width; - h = p_win->height; - - if(flag == TRUE) - { mvaddch(y, x, p_win->border.tl); - mvaddch(y, x + w, p_win->border.tr); - mvaddch(y + h, x, p_win->border.bl); - mvaddch(y + h, x + w, p_win->border.br); - mvhline(y, x + 1, p_win->border.ts, w - 1); - mvhline(y + h, x + 1, p_win->border.bs, w - 1); - mvvline(y + 1, x, p_win->border.ls, h - 1); - mvvline(y + 1, x + w, p_win->border.rs, h - 1); - } - else - for(j = y; j <= y + h; ++j) - for(i = x; i <= x + w; ++i) - mvaddch(j, i, ' '); - - refresh(); +void +create_box(WIN * p_win, bool flag) +{ + int i, j; + int x, y, w, h; + + x = p_win->startx; + y = p_win->starty; + w = p_win->width; + h = p_win->height; + + if (flag == TRUE) { + mvaddch(y, x, p_win->border.tl); + mvaddch(y, x + w, p_win->border.tr); + mvaddch(y + h, x, p_win->border.bl); + mvaddch(y + h, x + w, p_win->border.br); + mvhline(y, x + 1, p_win->border.ts, w - 1); + mvhline(y + h, x + 1, p_win->border.bs, w - 1); + mvvline(y + 1, x, p_win->border.ls, h - 1); + mvvline(y + 1, x + w, p_win->border.rs, h - 1); + + } else + for (j = y; j <= y + h; ++j) + for (i = x; i <= x + w; ++i) + mvaddch(j, i, ' '); + refresh(); }</span></pre> </div> </div> @@ -2535,44 +2568,48 @@ void create_box(WIN *p_win, bool flag) #include <string.h> #include <curses.h> -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string); -int main(int argc, char *argv[]) -{ initscr(); /* Start curses mode */ - if(has_colors() == FALSE) - { endwin(); - printf("Your terminal does not support color\n"); - exit(1); - } - start_color(); /* Start color */ - init_pair(1, COLOR_RED, COLOR_BLACK); +void print_in_middle(WINDOW *win, int starty, int startx, int width, const char *string); - attron(COLOR_PAIR(1)); - print_in_middle(stdscr, LINES / 2, 0, 0, "Viola !!! In color ..."); - attroff(COLOR_PAIR(1)); - getch(); +int +main(void) +{ + initscr(); /* Start curses mode */ + if (has_colors() == FALSE) { endwin(); + printf("Your terminal does not support color\n"); + exit(1); + } + start_color(); /* Start color */ + init_pair(1, COLOR_RED, COLOR_BLACK); + + attron(COLOR_PAIR(1)); + print_in_middle(stdscr, LINES / 2, 0, 0, "Viola !!! In color ..."); + attroff(COLOR_PAIR(1)); + getch(); + endwin(); } -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - mvwprintw(win, y, x, "%s", string); - refresh(); -} -</span></pre> +void +print_in_middle(WINDOW *win, int starty, int startx, int width, const char *string) +{ + int length, x, y; + float temp; + + if (win == NULL) + win = stdscr; + getyx(win, y, x); + if (startx != 0) + x = startx; + if (starty != 0) + y = starty; + if (width == 0) + width = 80; + + length = (int) strlen(string); + temp = (float) (width - length) / 2; + x = startx + (int) temp; + mvwprintw(win, y, x, "%s", string); + refresh(); +}</span></pre> </div> <p>As you can see, to start using color, you should first @@ -2724,93 +2761,100 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin "INLINEMEDIAOBJECT">#include <curses.h> #define WIDTH 30 -#define HEIGHT 10 +#define HEIGHT 10 int startx = 0; int starty = 0; -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Exit", - }; +const char *choices[] = +{ + "Choice 1", + "Choice 2", + "Choice 3", + "Choice 4", + "Exit", +}; int n_choices = sizeof(choices) / sizeof(char *); void print_menu(WINDOW *menu_win, int highlight); -int main() -{ WINDOW *menu_win; - int highlight = 1; - int choice = 0; - int c; - - initscr(); - clear(); - noecho(); - cbreak(); /* Line buffering disabled. pass on everything */ - startx = (80 - WIDTH) / 2; - starty = (24 - HEIGHT) / 2; - - menu_win = newwin(HEIGHT, WIDTH, starty, startx); - keypad(menu_win, TRUE); - mvprintw(0, 0, "Use arrow keys to go up and down, Press enter to select a choice"); - refresh(); +int +main(void) +{ + WINDOW *menu_win; + int highlight = 1; + int choice = 0; + int c; + + initscr(); + clear(); + noecho(); + cbreak(); /* Line buffering disabled. pass on everything */ + startx = (80 - WIDTH) / 2; + starty = (24 - HEIGHT) / 2; + + menu_win = newwin(HEIGHT, WIDTH, starty, startx); + keypad(menu_win, TRUE); + mvprintw(0, 0, + "Use arrow keys to go up and down, Press enter to select a choice"); + refresh(); + print_menu(menu_win, highlight); + while (1) { + c = wgetch(menu_win); + switch (c) { + case KEY_UP: + if (highlight == 1) + highlight = n_choices; + else + --highlight; + break; + case KEY_DOWN: + if (highlight == n_choices) + highlight = 1; + else + ++highlight; + break; + case 10: + choice = highlight; + break; + default: + mvprintw(24, 0, + "Character pressed is = %3d Hopefully it can be printed as '%c'", + c, c); + refresh(); + break; + } print_menu(menu_win, highlight); - while(1) - { c = wgetch(menu_win); - switch(c) - { case KEY_UP: - if(highlight == 1) - highlight = n_choices; - else - --highlight; - break; - case KEY_DOWN: - if(highlight == n_choices) - highlight = 1; - else - ++highlight; - break; - case 10: - choice = highlight; - break; - default: - mvprintw(24, 0, "Character pressed is = %3d Hopefully it can be printed as '%c'", c, c); - refresh(); - break; - } - print_menu(menu_win, highlight); - if(choice != 0) /* User did a choice come out of the infinite loop */ - break; - } - mvprintw(23, 0, "You chose choice %d with choice string %s\n", choice, choices[choice - 1]); - clrtoeol(); - refresh(); - endwin(); - return 0; + if (choice != 0) /* User did a choice come out of the infinite loop */ + break; + } + mvprintw(23, 0, "You chose choice %d with choice string %s\n", choice, + choices[choice - 1]); + clrtoeol(); + refresh(); + endwin(); + return 0; } -void print_menu(WINDOW *menu_win, int highlight) +void +print_menu(WINDOW *menu_win, int highlight) { - int x, y, i; - - x = 2; - y = 2; - box(menu_win, 0, 0); - for(i = 0; i < n_choices; ++i) - { if(highlight == i + 1) /* High light the present choice */ - { wattron(menu_win, A_REVERSE); - mvwprintw(menu_win, y, x, "%s", choices[i]); - wattroff(menu_win, A_REVERSE); - } - else - mvwprintw(menu_win, y, x, "%s", choices[i]); - ++y; - } - wrefresh(menu_win); -} -</span></pre> + int x, y, i; + + x = 2; + y = 2; + box(menu_win, 0, 0); + for (i = 0; i < n_choices; ++i) { + if (highlight == i + 1) /* Highlight the present choice */ + { + wattron(menu_win, A_REVERSE); + mvwprintw(menu_win, y, x, "%s", choices[i]); + wattroff(menu_win, A_REVERSE); + } else + mvwprintw(menu_win, y, x, "%s", choices[i]); + ++y; + } + wrefresh(menu_win); +}</span></pre> </div> </div> </div> @@ -2904,7 +2948,7 @@ void print_menu(WINDOW *menu_win, int highlight) short id; /* ID to distinguish multiple devices */ int x, y, z; /* event coordinates */ mmask_t bstate; /* button state bits */ - } </pre> + }</pre> <p>The <tt class="LITERAL">bstate</tt> is the main variable we are interested in. It tells the button state of the mouse.</p> @@ -2942,103 +2986,112 @@ void print_menu(WINDOW *menu_win, int highlight) int startx = 0; int starty = 0; -char *choices[] = { "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Exit", - }; +const char *choices[] = +{"Choice 1", + "Choice 2", + "Choice 3", + "Choice 4", + "Exit", +}; int n_choices = sizeof(choices) / sizeof(char *); void print_menu(WINDOW *menu_win, int highlight); void report_choice(int mouse_x, int mouse_y, int *p_choice); -int main() -{ int c, choice = 0; - WINDOW *menu_win; - MEVENT event; - - /* Initialize curses */ - initscr(); - clear(); - noecho(); - cbreak(); //Line buffering disabled. pass on everything - - /* Try to put the window in the middle of screen */ - startx = (80 - WIDTH) / 2; - starty = (24 - HEIGHT) / 2; - - attron(A_REVERSE); - mvprintw(23, 1, "Click on Exit to quit (Works best in a virtual console)"); - refresh(); - attroff(A_REVERSE); - - /* Print the menu for the first time */ - menu_win = newwin(HEIGHT, WIDTH, starty, startx); - keypad(menu_win, TRUE); - print_menu(menu_win, 1); - /* Get all the mouse events */ - mousemask(ALL_MOUSE_EVENTS, NULL); - - while(1) - { c = wgetch(menu_win); - switch(c) - { case KEY_MOUSE: - if(getmouse(&event) == OK) - { /* When the user clicks left mouse button */ - if(event.bstate & BUTTON1_PRESSED) - { report_choice(event.x + 1, event.y + 1, &choice); - if(choice == -1) //Exit chosen - goto end; - mvprintw(22, 1, "Choice made is : %d String Chosen is \"%10s\"", choice, choices[choice - 1]); - refresh(); - } - } - print_menu(menu_win, choice); - break; +int +main(void) +{ + int c, choice = 0; + WINDOW *menu_win; + MEVENT event; + + /* Initialize curses */ + initscr(); + clear(); + noecho(); + cbreak(); /* Line buffering disabled. pass everything */ + + /* Try to put the window in the middle of screen */ + startx = (80 - WIDTH) / 2; + starty = (24 - HEIGHT) / 2; + + attron(A_REVERSE); + mvprintw(23, 1, + "Click on Exit to quit (Works best in a virtual console)"); + refresh(); + attroff(A_REVERSE); + + /* Print the menu for the first time */ + menu_win = newwin(HEIGHT, WIDTH, starty, startx); + keypad(menu_win, TRUE); + print_menu(menu_win, 1); + /* Get all the mouse events */ + mousemask(ALL_MOUSE_EVENTS, NULL); + + while (1) { + c = wgetch(menu_win); + switch (c) { + case KEY_MOUSE: + if (getmouse(&event) == OK) { /* When the user clicks left mouse button */ + if (event.bstate & BUTTON1_PRESSED) { + report_choice(event.x + 1, event.y + 1, &choice); + if (choice == -1) /* Exit chosen */ + goto end; + mvprintw(22, 1, + "Choice made is : %d String Chosen is \"%10s\"", + choice, choices[choice - 1]); + refresh(); } + } + print_menu(menu_win, choice); + break; } -end: - endwin(); - return 0; + } + end: + endwin(); + return 0; } -void print_menu(WINDOW *menu_win, int highlight) +void +print_menu(WINDOW *menu_win, int highlight) { - int x, y, i; - - x = 2; - y = 2; - box(menu_win, 0, 0); - for(i = 0; i < n_choices; ++i) - { if(highlight == i + 1) - { wattron(menu_win, A_REVERSE); - mvwprintw(menu_win, y, x, "%s", choices[i]); - wattroff(menu_win, A_REVERSE); - } - else - mvwprintw(menu_win, y, x, "%s", choices[i]); - ++y; - } - wrefresh(menu_win); + int x, y, i; + + x = 2; + y = 2; + box(menu_win, 0, 0); + for (i = 0; i < n_choices; ++i) { + if (highlight == i + 1) { + wattron(menu_win, A_REVERSE); + mvwprintw(menu_win, y, x, "%s", choices[i]); + wattroff(menu_win, A_REVERSE); + } else + mvwprintw(menu_win, y, x, "%s", choices[i]); + ++y; + } + wrefresh(menu_win); } /* Report the choice according to mouse position */ -void report_choice(int mouse_x, int mouse_y, int *p_choice) -{ int i,j, choice; - - i = startx + 2; - j = starty + 3; - - for(choice = 0; choice < n_choices; ++choice) - if(mouse_y == j + choice && mouse_x >= i && mouse_x <= i + strlen(choices[choice])) - { if(choice == n_choices - 1) - *p_choice = -1; - else - *p_choice = choice + 1; - break; - } +void +report_choice(int mouse_x, int mouse_y, int *p_choice) +{ + int i, j, choice; + + i = startx + 2; + j = starty + 3; + + for (choice = 0; choice < n_choices; ++choice) + if (mouse_y == j + choice + && mouse_x >= i + && mouse_x <= i + (int) strlen(choices[choice])) { + if (choice == n_choices - 1) + *p_choice = -1; + else + *p_choice = choice + 1; + break; + } }</span></pre> </div> </div> @@ -3086,7 +3139,7 @@ void report_choice(int mouse_x, int mouse_y, int *p_choice) <pre class="PROGRAMLISTING"> getyx(win, y, x); /* win: window pointer - * y, x: y, x co-ordinates will be put into this variables + * y, x: y, x co-ordinates will be put into this variables */</pre> <p>The function getparyx() gets the beginning co-ordinates of the sub window relative to the main window. This is some @@ -3195,23 +3248,24 @@ void report_choice(int mouse_x, int mouse_y, int *p_choice) "INLINEMEDIAOBJECT">#include <stdlib.h> #include <curses.h> -int main() -{ - initscr(); /* Start curses mode */ - printw("Hello World !!!\n"); /* Print Hello World */ - refresh(); /* Print it on to the real screen */ - def_prog_mode(); /* Save the tty modes */ - endwin(); /* End curses mode temporarily */ - system("/bin/sh"); /* Do whatever you like in cooked mode */ - reset_prog_mode(); /* Return to the previous tty mode*/ - /* stored by def_prog_mode() */ - refresh(); /* Do refresh() to restore the */ - /* Screen contents */ - printw("Another String\n"); /* Back to curses use the full */ - refresh(); /* capabilities of curses */ - endwin(); /* End curses mode */ - - return 0; +int +main(void) +{ + initscr(); /* Start curses mode */ + printw("Hello World !!!\n"); /* Print Hello World */ + refresh(); /* Print it on to the real screen */ + def_prog_mode(); /* Save the tty modes */ + endwin(); /* End curses mode temporarily */ + system("/bin/sh"); /* Do whatever you like in cooked mode */ + reset_prog_mode(); /* Return to the previous tty mode */ + /* stored by def_prog_mode() */ + refresh(); /* Do refresh() to restore the */ + /* Screen contents */ + printw("Another String\n"); /* Back to curses use the full */ + refresh(); /* capabilities of curses */ + endwin(); /* End curses mode */ + + return 0; }</span></pre> </div> </div> @@ -3239,47 +3293,47 @@ int main() <pre class="PROGRAMLISTING"><span class= "INLINEMEDIAOBJECT">#include <curses.h> -int main() +int main(void) { - initscr(); - - printw("Upper left corner "); addch(ACS_ULCORNER); printw("\n"); - printw("Lower left corner "); addch(ACS_LLCORNER); printw("\n"); - printw("Lower right corner "); addch(ACS_LRCORNER); printw("\n"); - printw("Tee pointing right "); addch(ACS_LTEE); printw("\n"); - printw("Tee pointing left "); addch(ACS_RTEE); printw("\n"); - printw("Tee pointing up "); addch(ACS_BTEE); printw("\n"); - printw("Tee pointing down "); addch(ACS_TTEE); printw("\n"); - printw("Horizontal line "); addch(ACS_HLINE); printw("\n"); - printw("Vertical line "); addch(ACS_VLINE); printw("\n"); - printw("Large Plus or cross over "); addch(ACS_PLUS); printw("\n"); - printw("Scan Line 1 "); addch(ACS_S1); printw("\n"); - printw("Scan Line 3 "); addch(ACS_S3); printw("\n"); - printw("Scan Line 7 "); addch(ACS_S7); printw("\n"); - printw("Scan Line 9 "); addch(ACS_S9); printw("\n"); - printw("Diamond "); addch(ACS_DIAMOND); printw("\n"); - printw("Checker board (stipple) "); addch(ACS_CKBOARD); printw("\n"); - printw("Degree Symbol "); addch(ACS_DEGREE); printw("\n"); - printw("Plus/Minus Symbol "); addch(ACS_PLMINUS); printw("\n"); - printw("Bullet "); addch(ACS_BULLET); printw("\n"); - printw("Arrow Pointing Left "); addch(ACS_LARROW); printw("\n"); - printw("Arrow Pointing Right "); addch(ACS_RARROW); printw("\n"); - printw("Arrow Pointing Down "); addch(ACS_DARROW); printw("\n"); - printw("Arrow Pointing Up "); addch(ACS_UARROW); printw("\n"); - printw("Board of squares "); addch(ACS_BOARD); printw("\n"); - printw("Lantern Symbol "); addch(ACS_LANTERN); printw("\n"); - printw("Solid Square Block "); addch(ACS_BLOCK); printw("\n"); - printw("Less/Equal sign "); addch(ACS_LEQUAL); printw("\n"); - printw("Greater/Equal sign "); addch(ACS_GEQUAL); printw("\n"); - printw("Pi "); addch(ACS_PI); printw("\n"); - printw("Not equal "); addch(ACS_NEQUAL); printw("\n"); - printw("UK pound sign "); addch(ACS_STERLING); printw("\n"); + initscr(); + + printw("Upper left corner "); addch(ACS_ULCORNER); printw("\n"); + printw("Lower left corner "); addch(ACS_LLCORNER); printw("\n"); + printw("Lower right corner "); addch(ACS_LRCORNER); printw("\n"); + printw("Tee pointing right "); addch(ACS_LTEE); printw("\n"); + printw("Tee pointing left "); addch(ACS_RTEE); printw("\n"); + printw("Tee pointing up "); addch(ACS_BTEE); printw("\n"); + printw("Tee pointing down "); addch(ACS_TTEE); printw("\n"); + printw("Horizontal line "); addch(ACS_HLINE); printw("\n"); + printw("Vertical line "); addch(ACS_VLINE); printw("\n"); + printw("Large Plus or cross over "); addch(ACS_PLUS); printw("\n"); + printw("Scan Line 1 "); addch(ACS_S1); printw("\n"); + printw("Scan Line 3 "); addch(ACS_S3); printw("\n"); + printw("Scan Line 7 "); addch(ACS_S7); printw("\n"); + printw("Scan Line 9 "); addch(ACS_S9); printw("\n"); + printw("Diamond "); addch(ACS_DIAMOND); printw("\n"); + printw("Checker board (stipple) "); addch(ACS_CKBOARD); printw("\n"); + printw("Degree Symbol "); addch(ACS_DEGREE); printw("\n"); + printw("Plus/Minus Symbol "); addch(ACS_PLMINUS); printw("\n"); + printw("Bullet "); addch(ACS_BULLET); printw("\n"); + printw("Arrow Pointing Left "); addch(ACS_LARROW); printw("\n"); + printw("Arrow Pointing Right "); addch(ACS_RARROW); printw("\n"); + printw("Arrow Pointing Down "); addch(ACS_DARROW); printw("\n"); + printw("Arrow Pointing Up "); addch(ACS_UARROW); printw("\n"); + printw("Board of squares "); addch(ACS_BOARD); printw("\n"); + printw("Lantern Symbol "); addch(ACS_LANTERN); printw("\n"); + printw("Solid Square Block "); addch(ACS_BLOCK); printw("\n"); + printw("Less/Equal sign "); addch(ACS_LEQUAL); printw("\n"); + printw("Greater/Equal sign "); addch(ACS_GEQUAL); printw("\n"); + printw("Pi "); addch(ACS_PI); printw("\n"); + printw("Not equal "); addch(ACS_NEQUAL); printw("\n"); + printw("UK pound sign "); addch(ACS_STERLING); printw("\n"); - refresh(); - getch(); - endwin(); + refresh(); + getch(); + endwin(); - return 0; + return 0; }</span></pre> </div> </div> @@ -3415,42 +3469,52 @@ int main() <pre class="PROGRAMLISTING"><span class= "INLINEMEDIAOBJECT">#include <panel.h> -int main() -{ WINDOW *my_wins[3]; - PANEL *my_panels[3]; - int lines = 10, cols = 40, y = 2, x = 4, i; - - initscr(); - cbreak(); - noecho(); - - /* Create windows for the panels */ - my_wins[0] = newwin(lines, cols, y, x); - my_wins[1] = newwin(lines, cols, y + 1, x + 5); - my_wins[2] = newwin(lines, cols, y + 2, x + 10); - - /* - * Create borders around the windows so that you can see the effect - * of panels - */ - for(i = 0; i < 3; ++i) - box(my_wins[i], 0, 0); - - /* Attach a panel to each window */ /* Order is bottom up */ - my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */ - my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */ - my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */ - - /* Update the stacking order. 2nd panel will be on top */ - update_panels(); - - /* Show it on the screen */ - doupdate(); - - getch(); - endwin(); -} -</span></pre> +int +main(void) +{ + WINDOW *my_wins[3]; + PANEL *my_panels[3]; + int lines = 10, cols = 40, y = 2, x = 4, i; + + initscr(); + cbreak(); + noecho(); + + /* Create windows for the panels */ + my_wins[0] = newwin(lines, cols, y, x); + my_wins[1] = newwin(lines, cols, y + 1, x + 5); + my_wins[2] = newwin(lines, cols, y + 2, x + 10); + + /* + * Create borders around the windows so that you can see the effect + * of panels + */ + for (i = 0; i < 3; ++i) + box(my_wins[i], 0, 0); + + /* Attach a panel to each window */ + /* Order is bottom up */ + /* Push 0, order: stdscr-0 */ + /* Push 1, order: stdscr-0-1 */ + /* Push 2, order: stdscr-0-1-2 */ + for (i = 0; i < 3; ++i) + my_panels[i] = new_panel(my_wins[i]); + + /* Update the stacking order. Last-created panel will be on top */ + update_panels(); + + /* Show it on the screen */ + doupdate(); + + getch(); + + /* Deleting panels does not erase their window */ + for (i = 0; i < 3; ++i) + del_panel(my_panels[i]); + + endwin(); + return 0; +}</span></pre> </div> <p>As you can see, above program follows a simple flow as @@ -3484,116 +3548,128 @@ int main() #define NCOLS 40 void init_wins(WINDOW **wins, int n); -void win_show(WINDOW *win, char *label, int label_color); -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); - -int main() -{ WINDOW *my_wins[3]; - PANEL *my_panels[3]; - PANEL *top; - int ch; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize all the colors */ - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_BLUE, COLOR_BLACK); - init_pair(4, COLOR_CYAN, COLOR_BLACK); - - init_wins(my_wins, 3); - - /* Attach a panel to each window */ /* Order is bottom up */ - my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */ - my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */ - my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */ - - /* Set up the user pointers to the next panel */ - set_panel_userptr(my_panels[0], my_panels[1]); - set_panel_userptr(my_panels[1], my_panels[2]); - set_panel_userptr(my_panels[2], my_panels[0]); - - /* Update the stacking order. 2nd panel will be on top */ - update_panels(); +void win_show(WINDOW *win, const char *label, int label_color); +void print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color); - /* Show it on the screen */ - attron(COLOR_PAIR(4)); - mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)"); - attroff(COLOR_PAIR(4)); - doupdate(); - - top = my_panels[2]; - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case 9: - top = (PANEL *)panel_userptr(top); - top_panel(top); - break; - } - update_panels(); - doupdate(); +int +main(void) +{ + WINDOW *my_wins[3]; + PANEL *my_panels[3]; + PANEL *top; + int ch; + + /* Initialize curses */ + initscr(); + start_color(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + + /* Initialize all the colors */ + init_pair(1, COLOR_RED, COLOR_BLACK); + init_pair(2, COLOR_GREEN, COLOR_BLACK); + init_pair(3, COLOR_BLUE, COLOR_BLACK); + init_pair(4, COLOR_CYAN, COLOR_BLACK); + + init_wins(my_wins, 3); + + /* Attach a panel to each window */ + /* Order is bottom up */ + my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */ + my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */ + my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */ + + /* Set up the user pointers to the next panel */ + set_panel_userptr(my_panels[0], my_panels[1]); + set_panel_userptr(my_panels[1], my_panels[2]); + set_panel_userptr(my_panels[2], my_panels[0]); + + /* Update the stacking order. 2nd panel will be on top */ + update_panels(); + + /* Show it on the screen */ + attron(COLOR_PAIR(4)); + mvprintw(LINES - 2, 0, + "Use tab to browse through the windows (F1 to Exit)"); + attroff(COLOR_PAIR(4)); + doupdate(); + + top = my_panels[2]; + while ((ch = getch()) != KEY_F(1)) { + switch (ch) { + case 9: + top = (PANEL *) panel_userptr(top); + top_panel(top); + break; } - endwin(); - return 0; + update_panels(); + doupdate(); + } + endwin(); + return 0; } /* Put all the windows */ -void init_wins(WINDOW **wins, int n) -{ int x, y, i; - char label[80]; - - y = 2; - x = 10; - for(i = 0; i < n; ++i) - { wins[i] = newwin(NLINES, NCOLS, y, x); - sprintf(label, "Window Number %d", i + 1); - win_show(wins[i], label, i + 1); - y += 3; - x += 7; - } +void +init_wins(WINDOW **wins, int n) +{ + int x, y, i; + char label[80]; + + y = 2; + x = 10; + for (i = 0; i < n; ++i) { + wins[i] = newwin(NLINES, NCOLS, y, x); + sprintf(label, "Window Number %d", i + 1); + win_show(wins[i], label, i + 1); + y += 3; + x += 7; + } } /* Show the window with a border and a label */ -void win_show(WINDOW *win, char *label, int label_color) -{ int startx, starty, height, width; - - getbegyx(win, starty, startx); - getmaxyx(win, height, width); - - box(win, 0, 0); - mvwaddch(win, 2, 0, ACS_LTEE); - mvwhline(win, 2, 1, ACS_HLINE, width - 2); - mvwaddch(win, 2, width - 1, ACS_RTEE); - - print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color)); +void +win_show(WINDOW *win, const char *label, int label_color) +{ + int height, width; + + getmaxyx(win, height, width); + (void) height; + + box(win, 0, 0); + mvwaddch(win, 2, 0, ACS_LTEE); + mvwhline(win, 2, 1, ACS_HLINE, width - 2); + mvwaddch(win, 2, width - 1, ACS_RTEE); + + print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color)); } -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); +void +print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color) +{ + int length, x, y; + float temp; + + if (win == NULL) + win = stdscr; + getyx(win, y, x); + if (startx != 0) + x = startx; + if (starty != 0) + y = starty; + if (width == 0) + width = 80; + + length = (int) strlen(string); + temp = (float) (width - length) / 2; + x = startx + (int) temp; + wattron(win, color); + mvwprintw(win, y, x, "%s", string); + wattroff(win, color); + refresh(); }</span></pre> </div> </div> @@ -3660,236 +3736,253 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin #include <panel.h> typedef struct _PANEL_DATA { - int x, y, w, h; - char label[80]; - int label_color; - PANEL *next; -}PANEL_DATA; + int x, y, w, h; + char label[80]; + int label_color; + PANEL *next; +} PANEL_DATA; #define NLINES 10 #define NCOLS 40 void init_wins(WINDOW **wins, int n); -void win_show(WINDOW *win, char *label, int label_color); -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); +void win_show(WINDOW *win, const char *label, int label_color); +void print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color); void set_user_ptrs(PANEL **panels, int n); -int main() -{ WINDOW *my_wins[3]; - PANEL *my_panels[3]; - PANEL_DATA *top; - PANEL *stack_top; - WINDOW *temp_win, *old_win; - int ch; - int newx, newy, neww, newh; - int size = FALSE, move = FALSE; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize all the colors */ - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_BLUE, COLOR_BLACK); - init_pair(4, COLOR_CYAN, COLOR_BLACK); - - init_wins(my_wins, 3); - - /* Attach a panel to each window */ /* Order is bottom up */ - my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */ - my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */ - my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */ - - set_user_ptrs(my_panels, 3); - /* Update the stacking order. 2nd panel will be on top */ - update_panels(); +int +main(void) +{ + WINDOW *my_wins[3]; + PANEL *my_panels[3]; + PANEL_DATA *top; + PANEL *stack_top; + WINDOW *temp_win, *old_win; + int ch; + int newx, newy, neww, newh; + int size = FALSE, move = FALSE; + + /* Initialize curses */ + initscr(); + start_color(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + + /* Initialize all the colors */ + init_pair(1, COLOR_RED, COLOR_BLACK); + init_pair(2, COLOR_GREEN, COLOR_BLACK); + init_pair(3, COLOR_BLUE, COLOR_BLACK); + init_pair(4, COLOR_CYAN, COLOR_BLACK); + + init_wins(my_wins, 3); + + /* Attach a panel to each window */ + /* Order is bottom up */ + my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */ + my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */ + my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */ + + set_user_ptrs(my_panels, 3); + /* Update the stacking order. 2nd panel will be on top */ + update_panels(); + + /* Show it on the screen */ + attron(COLOR_PAIR(4)); + mvprintw(LINES - 3, 0, "Use 'm' for moving, 'r' for resizing"); + mvprintw(LINES - 2, 0, + "Use tab to browse through the windows (F1 to Exit)"); + attroff(COLOR_PAIR(4)); + doupdate(); + + stack_top = my_panels[2]; + top = (PANEL_DATA *) panel_userptr(stack_top); + newx = top->x; + newy = top->y; + neww = top->w; + newh = top->h; + while ((ch = getch()) != KEY_F(1)) { + switch (ch) { + case 9: /* Tab */ + top = (PANEL_DATA *) panel_userptr(stack_top); + top_panel(top->next); + stack_top = top->next; + top = (PANEL_DATA *) panel_userptr(stack_top); + newx = top->x; + newy = top->y; + neww = top->w; + newh = top->h; + break; + case 'r': /* Re-Size */ + size = TRUE; + attron(COLOR_PAIR(4)); + mvprintw(LINES - 4, 0, + "Entered Resizing :Use Arrow Keys to resize and press <ENTER> to end resizing"); + refresh(); + attroff(COLOR_PAIR(4)); + break; + case 'm': /* Move */ + attron(COLOR_PAIR(4)); + mvprintw(LINES - 4, 0, + "Entered Moving: Use Arrow Keys to Move and press <ENTER> to end moving"); + refresh(); + attroff(COLOR_PAIR(4)); + move = TRUE; + break; + case KEY_LEFT: + if (size == TRUE) { + --newx; + ++neww; + } + if (move == TRUE) + --newx; + break; + case KEY_RIGHT: + if (size == TRUE) { + ++newx; + --neww; + } + if (move == TRUE) + ++newx; + break; + case KEY_UP: + if (size == TRUE) { + --newy; + ++newh; + } + if (move == TRUE) + --newy; + break; + case KEY_DOWN: + if (size == TRUE) { + ++newy; + --newh; + } + if (move == TRUE) + ++newy; + break; + case 10: /* Enter */ + move(LINES - 4, 0); + clrtoeol(); + refresh(); + if (size == TRUE) { + old_win = panel_window(stack_top); + temp_win = newwin(newh, neww, newy, newx); + replace_panel(stack_top, temp_win); + win_show(temp_win, top->label, top->label_color); + delwin(old_win); + size = FALSE; + } + if (move == TRUE) { + move_panel(stack_top, newy, newx); + move = FALSE; + } + break; - /* Show it on the screen */ + } attron(COLOR_PAIR(4)); mvprintw(LINES - 3, 0, "Use 'm' for moving, 'r' for resizing"); - mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)"); + mvprintw(LINES - 2, 0, + "Use tab to browse through the windows (F1 to Exit)"); attroff(COLOR_PAIR(4)); + refresh(); + update_panels(); doupdate(); - - stack_top = my_panels[2]; - top = (PANEL_DATA *)panel_userptr(stack_top); - newx = top->x; - newy = top->y; - neww = top->w; - newh = top->h; - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case 9: /* Tab */ - top = (PANEL_DATA *)panel_userptr(stack_top); - top_panel(top->next); - stack_top = top->next; - top = (PANEL_DATA *)panel_userptr(stack_top); - newx = top->x; - newy = top->y; - neww = top->w; - newh = top->h; - break; - case 'r': /* Re-Size*/ - size = TRUE; - attron(COLOR_PAIR(4)); - mvprintw(LINES - 4, 0, "Entered Resizing :Use Arrow Keys to resize and press <ENTER> to end resizing"); - refresh(); - attroff(COLOR_PAIR(4)); - break; - case 'm': /* Move */ - attron(COLOR_PAIR(4)); - mvprintw(LINES - 4, 0, "Entered Moving: Use Arrow Keys to Move and press <ENTER> to end moving"); - refresh(); - attroff(COLOR_PAIR(4)); - move = TRUE; - break; - case KEY_LEFT: - if(size == TRUE) - { --newx; - ++neww; - } - if(move == TRUE) - --newx; - break; - case KEY_RIGHT: - if(size == TRUE) - { ++newx; - --neww; - } - if(move == TRUE) - ++newx; - break; - case KEY_UP: - if(size == TRUE) - { --newy; - ++newh; - } - if(move == TRUE) - --newy; - break; - case KEY_DOWN: - if(size == TRUE) - { ++newy; - --newh; - } - if(move == TRUE) - ++newy; - break; - case 10: /* Enter */ - move(LINES - 4, 0); - clrtoeol(); - refresh(); - if(size == TRUE) - { old_win = panel_window(stack_top); - temp_win = newwin(newh, neww, newy, newx); - replace_panel(stack_top, temp_win); - win_show(temp_win, top->label, top->label_color); - delwin(old_win); - size = FALSE; - } - if(move == TRUE) - { move_panel(stack_top, newy, newx); - move = FALSE; - } - break; - - } - attron(COLOR_PAIR(4)); - mvprintw(LINES - 3, 0, "Use 'm' for moving, 'r' for resizing"); - mvprintw(LINES - 2, 0, "Use tab to browse through the windows (F1 to Exit)"); - attroff(COLOR_PAIR(4)); - refresh(); - update_panels(); - doupdate(); - } - endwin(); - return 0; + } + endwin(); + return 0; } /* Put all the windows */ -void init_wins(WINDOW **wins, int n) -{ int x, y, i; - char label[80]; - - y = 2; - x = 10; - for(i = 0; i < n; ++i) - { wins[i] = newwin(NLINES, NCOLS, y, x); - sprintf(label, "Window Number %d", i + 1); - win_show(wins[i], label, i + 1); - y += 3; - x += 7; - } +void +init_wins(WINDOW **wins, int n) +{ + int x, y, i; + char label[80]; + + y = 2; + x = 10; + for (i = 0; i < n; ++i) { + wins[i] = newwin(NLINES, NCOLS, y, x); + sprintf(label, "Window Number %d", i + 1); + win_show(wins[i], label, i + 1); + y += 3; + x += 7; + } } /* Set the PANEL_DATA structures for individual panels */ -void set_user_ptrs(PANEL **panels, int n) -{ PANEL_DATA *ptrs; - WINDOW *win; - int x, y, w, h, i; - char temp[80]; - - ptrs = (PANEL_DATA *)calloc(n, sizeof(PANEL_DATA)); - - for(i = 0;i < n; ++i) - { win = panel_window(panels[i]); - getbegyx(win, y, x); - getmaxyx(win, h, w); - ptrs[i].x = x; - ptrs[i].y = y; - ptrs[i].w = w; - ptrs[i].h = h; - sprintf(temp, "Window Number %d", i + 1); - strcpy(ptrs[i].label, temp); - ptrs[i].label_color = i + 1; - if(i + 1 == n) - ptrs[i].next = panels[0]; - else - ptrs[i].next = panels[i + 1]; - set_panel_userptr(panels[i], &ptrs[i]); - } +void +set_user_ptrs(PANEL **panels, int n) +{ + PANEL_DATA *ptrs; + WINDOW *win; + int x, y, w, h, i; + char temp[80]; + + ptrs = (PANEL_DATA *) calloc((size_t) n, sizeof(PANEL_DATA)); + + for (i = 0; i < n; ++i) { + win = panel_window(panels[i]); + getbegyx(win, y, x); + getmaxyx(win, h, w); + ptrs[i].x = x; + ptrs[i].y = y; + ptrs[i].w = w; + ptrs[i].h = h; + sprintf(temp, "Window Number %d", i + 1); + strcpy(ptrs[i].label, temp); + ptrs[i].label_color = i + 1; + if (i + 1 == n) + ptrs[i].next = panels[0]; + else + ptrs[i].next = panels[i + 1]; + set_panel_userptr(panels[i], &ptrs[i]); + } } /* Show the window with a border and a label */ -void win_show(WINDOW *win, char *label, int label_color) -{ int startx, starty, height, width; - - getbegyx(win, starty, startx); - getmaxyx(win, height, width); - - box(win, 0, 0); - mvwaddch(win, 2, 0, ACS_LTEE); - mvwhline(win, 2, 1, ACS_HLINE, width - 2); - mvwaddch(win, 2, width - 1, ACS_RTEE); - - print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color)); +void +win_show(WINDOW *win, const char *label, int label_color) +{ + int height, width; + + getmaxyx(win, height, width); + (void) height; + + box(win, 0, 0); + mvwaddch(win, 2, 0, ACS_LTEE); + mvwhline(win, 2, 1, ACS_HLINE, width - 2); + mvwaddch(win, 2, width - 1, ACS_RTEE); + + print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color)); } -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); +void +print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color) +{ + int length, x, y; + float temp; + + if (win == NULL) + win = stdscr; + getyx(win, y, x); + if (startx != 0) + x = startx; + if (starty != 0) + y = starty; + if (width == 0) + width = 80; + + length = (int) strlen(string); + temp = (float) (width - length) / 2; + x = startx + (int) temp; + wattron(win, color); + mvwprintw(win, y, x, "%s", string); + wattroff(win, color); + refresh(); }</span></pre> </div> @@ -3952,158 +4045,167 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin #include <panel.h> typedef struct _PANEL_DATA { - int hide; /* TRUE if panel is hidden */ -}PANEL_DATA; + int hide; /* TRUE if panel is hidden */ +} PANEL_DATA; #define NLINES 10 #define NCOLS 40 void init_wins(WINDOW **wins, int n); -void win_show(WINDOW *win, char *label, int label_color); -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); - -int main() -{ WINDOW *my_wins[3]; - PANEL *my_panels[3]; - PANEL_DATA panel_datas[3]; - PANEL_DATA *temp; - int ch; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize all the colors */ - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_BLUE, COLOR_BLACK); - init_pair(4, COLOR_CYAN, COLOR_BLACK); - - init_wins(my_wins, 3); - - /* Attach a panel to each window */ /* Order is bottom up */ - my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */ - my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */ - my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */ - - /* Initialize panel data saying that nothing is hidden */ - panel_datas[0].hide = FALSE; - panel_datas[1].hide = FALSE; - panel_datas[2].hide = FALSE; - - set_panel_userptr(my_panels[0], &panel_datas[0]); - set_panel_userptr(my_panels[1], &panel_datas[1]); - set_panel_userptr(my_panels[2], &panel_datas[2]); - - /* Update the stacking order. 2nd panel will be on top */ - update_panels(); - - /* Show it on the screen */ - attron(COLOR_PAIR(4)); - mvprintw(LINES - 3, 0, "Show or Hide a window with 'a'(first window) 'b'(Second Window) 'c'(Third Window)"); - mvprintw(LINES - 2, 0, "F1 to Exit"); +void win_show(WINDOW *win, const char *label, int label_color); +void print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color); - attroff(COLOR_PAIR(4)); - doupdate(); - - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case 'a': - temp = (PANEL_DATA *)panel_userptr(my_panels[0]); - if(temp->hide == FALSE) - { hide_panel(my_panels[0]); - temp->hide = TRUE; - } - else - { show_panel(my_panels[0]); - temp->hide = FALSE; - } - break; - case 'b': - temp = (PANEL_DATA *)panel_userptr(my_panels[1]); - if(temp->hide == FALSE) - { hide_panel(my_panels[1]); - temp->hide = TRUE; - } - else - { show_panel(my_panels[1]); - temp->hide = FALSE; - } - break; - case 'c': - temp = (PANEL_DATA *)panel_userptr(my_panels[2]); - if(temp->hide == FALSE) - { hide_panel(my_panels[2]); - temp->hide = TRUE; - } - else - { show_panel(my_panels[2]); - temp->hide = FALSE; - } - break; - } - update_panels(); - doupdate(); +int +main(void) +{ + WINDOW *my_wins[3]; + PANEL *my_panels[3]; + PANEL_DATA panel_datas[3]; + PANEL_DATA *temp; + int ch; + + /* Initialize curses */ + initscr(); + start_color(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + + /* Initialize all the colors */ + init_pair(1, COLOR_RED, COLOR_BLACK); + init_pair(2, COLOR_GREEN, COLOR_BLACK); + init_pair(3, COLOR_BLUE, COLOR_BLACK); + init_pair(4, COLOR_CYAN, COLOR_BLACK); + + init_wins(my_wins, 3); + + /* Attach a panel to each window */ + /* Order is bottom up */ + my_panels[0] = new_panel(my_wins[0]); /* Push 0, order: stdscr-0 */ + my_panels[1] = new_panel(my_wins[1]); /* Push 1, order: stdscr-0-1 */ + my_panels[2] = new_panel(my_wins[2]); /* Push 2, order: stdscr-0-1-2 */ + + /* Initialize panel data saying that nothing is hidden */ + panel_datas[0].hide = FALSE; + panel_datas[1].hide = FALSE; + panel_datas[2].hide = FALSE; + + set_panel_userptr(my_panels[0], &panel_datas[0]); + set_panel_userptr(my_panels[1], &panel_datas[1]); + set_panel_userptr(my_panels[2], &panel_datas[2]); + + /* Update the stacking order. 2nd panel will be on top */ + update_panels(); + + /* Show it on the screen */ + attron(COLOR_PAIR(4)); + mvprintw(LINES - 3, 0, + "Show or Hide a window with 'a'(first window) 'b'(Second Window) 'c'(Third Window)"); + mvprintw(LINES - 2, 0, "F1 to Exit"); + + attroff(COLOR_PAIR(4)); + doupdate(); + + while ((ch = getch()) != KEY_F(1)) { + switch (ch) { + case 'a': + temp = (PANEL_DATA *) panel_userptr(my_panels[0]); + if (temp->hide == FALSE) { + hide_panel(my_panels[0]); + temp->hide = TRUE; + } else { + show_panel(my_panels[0]); + temp->hide = FALSE; + } + break; + case 'b': + temp = (PANEL_DATA *) panel_userptr(my_panels[1]); + if (temp->hide == FALSE) { + hide_panel(my_panels[1]); + temp->hide = TRUE; + } else { + show_panel(my_panels[1]); + temp->hide = FALSE; + } + break; + case 'c': + temp = (PANEL_DATA *) panel_userptr(my_panels[2]); + if (temp->hide == FALSE) { + hide_panel(my_panels[2]); + temp->hide = TRUE; + } else { + show_panel(my_panels[2]); + temp->hide = FALSE; + } + break; } - endwin(); - return 0; + update_panels(); + doupdate(); + } + endwin(); + return 0; } /* Put all the windows */ -void init_wins(WINDOW **wins, int n) -{ int x, y, i; - char label[80]; - - y = 2; - x = 10; - for(i = 0; i < n; ++i) - { wins[i] = newwin(NLINES, NCOLS, y, x); - sprintf(label, "Window Number %d", i + 1); - win_show(wins[i], label, i + 1); - y += 3; - x += 7; - } +void +init_wins(WINDOW **wins, int n) +{ + int x, y, i; + char label[80]; + + y = 2; + x = 10; + for (i = 0; i < n; ++i) { + wins[i] = newwin(NLINES, NCOLS, y, x); + sprintf(label, "Window Number %d", i + 1); + win_show(wins[i], label, i + 1); + y += 3; + x += 7; + } } /* Show the window with a border and a label */ -void win_show(WINDOW *win, char *label, int label_color) -{ int startx, starty, height, width; - - getbegyx(win, starty, startx); - getmaxyx(win, height, width); - - box(win, 0, 0); - mvwaddch(win, 2, 0, ACS_LTEE); - mvwhline(win, 2, 1, ACS_HLINE, width - 2); - mvwaddch(win, 2, width - 1, ACS_RTEE); - - print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color)); +void +win_show(WINDOW *win, const char *label, int label_color) +{ + int height, width; + + getmaxyx(win, height, width); + (void) height; + + box(win, 0, 0); + mvwaddch(win, 2, 0, ACS_LTEE); + mvwhline(win, 2, 1, ACS_HLINE, width - 2); + mvwaddch(win, 2, width - 1, ACS_RTEE); + + print_in_middle(win, 1, 0, width, label, COLOR_PAIR(label_color)); } -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); +void +print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color) +{ + int length, x, y; + float temp; + + if (win == NULL) + win = stdscr; + getyx(win, y, x); + if (startx != 0) + x = startx; + if (starty != 0) + y = starty; + if (width == 0) + width = 80; + + length = (int) strlen(string); + temp = (float) (width - length) / 2; + x = startx + (int) temp; + wattron(win, color); + mvwprintw(win, y, x, "%s", string); + wattroff(win, color); + refresh(); }</span></pre> </div> </div> @@ -4235,56 +4337,56 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin #define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) #define CTRLD 4 -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Exit", - }; - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - int n_choices, i; - ITEM *cur_item; - - - initscr(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *)); - - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - my_items[n_choices] = (ITEM *)NULL; - - my_menu = new_menu((ITEM **)my_items); - mvprintw(LINES - 2, 0, "F1 to Exit"); - post_menu(my_menu); - refresh(); +const char *choices[] = +{ + "Choice 1", + "Choice 2", + "Choice 3", + "Choice 4", + "Exit", +}; + +int +main(void) +{ + ITEM **my_items; + int c; + MENU *my_menu; + int n_choices, i; + + initscr(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + + n_choices = ARRAY_SIZE(choices); + my_items = (ITEM **) calloc((size_t) (n_choices + 1), sizeof(ITEM *)); + + for (i = 0; i < n_choices; ++i) + my_items[i] = new_item(choices[i], choices[i]); + my_items[n_choices] = (ITEM *) NULL; + + my_menu = new_menu((ITEM **) my_items); + mvprintw(LINES - 2, 0, "F1 to Exit"); + post_menu(my_menu); + refresh(); - while((c = getch()) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - } - } + while ((c = getch()) != KEY_F(1)) { + switch (c) { + case KEY_DOWN: + menu_driver(my_menu, REQ_DOWN_ITEM); + break; + case KEY_UP: + menu_driver(my_menu, REQ_UP_ITEM); + break; + } + } - free_item(my_items[0]); - free_item(my_items[1]); - free_menu(my_menu); - endwin(); -} - </span></pre> + free_item(my_items[0]); + free_item(my_items[1]); + free_menu(my_menu); + endwin(); +}</span></pre> </div> <p>This program demonstrates the basic concepts involved in @@ -4304,21 +4406,21 @@ int main() requests.</p> <pre class= - "PROGRAMLISTING"> REQ_LEFT_ITEM Move left to an item. - REQ_RIGHT_ITEM Move right to an item. - REQ_UP_ITEM Move up to an item. - REQ_DOWN_ITEM Move down to an item. - REQ_SCR_ULINE Scroll up a line. - REQ_SCR_DLINE Scroll down a line. - REQ_SCR_DPAGE Scroll down a page. - REQ_SCR_UPAGE Scroll up a page. + "PROGRAMLISTING"> REQ_LEFT_ITEM Move left to an item. + REQ_RIGHT_ITEM Move right to an item. + REQ_UP_ITEM Move up to an item. + REQ_DOWN_ITEM Move down to an item. + REQ_SCR_ULINE Scroll up a line. + REQ_SCR_DLINE Scroll down a line. + REQ_SCR_DPAGE Scroll down a page. + REQ_SCR_UPAGE Scroll up a page. REQ_FIRST_ITEM Move to the first item. - REQ_LAST_ITEM Move to the last item. - REQ_NEXT_ITEM Move to the next item. - REQ_PREV_ITEM Move to the previous item. - REQ_TOGGLE_ITEM Select/deselect an item. - REQ_CLEAR_PATTERN Clear the menu pattern buffer. - REQ_BACK_PATTERN Delete the previous character from the pattern buffer. + REQ_LAST_ITEM Move to the last item. + REQ_NEXT_ITEM Move to the next item. + REQ_PREV_ITEM Move to the previous item. + REQ_TOGGLE_ITEM Select/deselect an item. + REQ_CLEAR_PATTERN Clear the menu pattern buffer. + REQ_BACK_PATTERN Delete the previous character from the pattern buffer. REQ_NEXT_MATCH Move to the next item matching the pattern match. REQ_PREV_MATCH Move to the previous item matching the pattern match. </pre> <p>Don't get overwhelmed by the number of options. We will @@ -4485,105 +4587,113 @@ int main() #define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) #define CTRLD 4 -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Exit", - (char *)NULL, - }; -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - WINDOW *my_menu_win; - int n_choices, i; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - init_pair(1, COLOR_RED, COLOR_BLACK); - - /* Create items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - - /* Create menu */ - my_menu = new_menu((ITEM **)my_items); - - /* Create the window to be associated with the menu */ - my_menu_win = newwin(10, 40, 4, 4); - keypad(my_menu_win, TRUE); - - /* Set main window and sub window */ - set_menu_win(my_menu, my_menu_win); - set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1)); - - /* Set menu mark to the string " * " */ - set_menu_mark(my_menu, " * "); - - /* Print a border around the main window and print a title */ - box(my_menu_win, 0, 0); - print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1)); - mvwaddch(my_menu_win, 2, 0, ACS_LTEE); - mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38); - mvwaddch(my_menu_win, 2, 39, ACS_RTEE); - mvprintw(LINES - 2, 0, "F1 to exit"); - refresh(); - - /* Post the menu */ - post_menu(my_menu); +const char *choices[] = +{ + "Choice 1", + "Choice 2", + "Choice 3", + "Choice 4", + "Exit", + (char *) NULL, +}; + +void print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color); + +int +main(void) +{ + ITEM **my_items; + int c; + MENU *my_menu; + WINDOW *my_menu_win; + int n_choices, i; + + /* Initialize curses */ + initscr(); + start_color(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + init_pair(1, COLOR_RED, COLOR_BLACK); + + /* Create items */ + n_choices = ARRAY_SIZE(choices); + my_items = (ITEM **) calloc((size_t) n_choices, sizeof(ITEM *)); + for (i = 0; i < n_choices; ++i) + my_items[i] = new_item(choices[i], choices[i]); + + /* Create menu */ + my_menu = new_menu((ITEM **) my_items); + + /* Create the window to be associated with the menu */ + my_menu_win = newwin(10, 40, 4, 4); + keypad(my_menu_win, TRUE); + + /* Set main window and sub window */ + set_menu_win(my_menu, my_menu_win); + set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1)); + + /* Set menu mark to the string " * " */ + set_menu_mark(my_menu, " * "); + + /* Print a border around the main window and print a title */ + box(my_menu_win, 0, 0); + print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1)); + mvwaddch(my_menu_win, 2, 0, ACS_LTEE); + mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38); + mvwaddch(my_menu_win, 2, 39, ACS_RTEE); + mvprintw(LINES - 2, 0, "F1 to exit"); + refresh(); + + /* Post the menu */ + post_menu(my_menu); + wrefresh(my_menu_win); + + while ((c = wgetch(my_menu_win)) != KEY_F(1)) { + switch (c) { + case KEY_DOWN: + menu_driver(my_menu, REQ_DOWN_ITEM); + break; + case KEY_UP: + menu_driver(my_menu, REQ_UP_ITEM); + break; + } wrefresh(my_menu_win); + } - while((c = wgetch(my_menu_win)) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - } - wrefresh(my_menu_win); - } - - /* Unpost and free all the memory taken up */ - unpost_menu(my_menu); - free_menu(my_menu); - for(i = 0; i < n_choices; ++i) - free_item(my_items[i]); - endwin(); + /* Unpost and free all the memory taken up */ + unpost_menu(my_menu); + free_menu(my_menu); + for (i = 0; i < n_choices; ++i) + free_item(my_items[i]); + endwin(); } -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); +void +print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color) +{ + int length, x, y; + float temp; + + if (win == NULL) + win = stdscr; + getyx(win, y, x); + if (startx != 0) + x = startx; + if (starty != 0) + y = starty; + if (width == 0) + width = 80; + + length = (int) strlen(string); + temp = (float) (width - length) / 2; + x = startx + (int) temp; + wattron(win, color); + mvwprintw(win, y, x, "%s", string); + wattroff(win, color); + refresh(); }</span></pre> </div> @@ -4624,123 +4734,132 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin #define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) #define CTRLD 4 -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Choice 5", - "Choice 6", - "Choice 7", - "Choice 8", - "Choice 9", - "Choice 10", - "Exit", - (char *)NULL, - }; -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - WINDOW *my_menu_win; - int n_choices, i; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_CYAN, COLOR_BLACK); - - /* Create items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - - /* Create menu */ - my_menu = new_menu((ITEM **)my_items); - - /* Create the window to be associated with the menu */ - my_menu_win = newwin(10, 40, 4, 4); - keypad(my_menu_win, TRUE); - - /* Set main window and sub window */ - set_menu_win(my_menu, my_menu_win); - set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1)); - set_menu_format(my_menu, 5, 1); - - /* Set menu mark to the string " * " */ - set_menu_mark(my_menu, " * "); - - /* Print a border around the main window and print a title */ - box(my_menu_win, 0, 0); - print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1)); - mvwaddch(my_menu_win, 2, 0, ACS_LTEE); - mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38); - mvwaddch(my_menu_win, 2, 39, ACS_RTEE); - - /* Post the menu */ - post_menu(my_menu); +const char *choices[] = +{ + "Choice 1", + "Choice 2", + "Choice 3", + "Choice 4", + "Choice 5", + "Choice 6", + "Choice 7", + "Choice 8", + "Choice 9", + "Choice 10", + "Exit", + (char *) NULL, +}; + +void print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color); + +int +main(void) +{ + ITEM **my_items; + int c; + MENU *my_menu; + WINDOW *my_menu_win; + int n_choices, i; + + /* Initialize curses */ + initscr(); + start_color(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + init_pair(1, COLOR_RED, COLOR_BLACK); + init_pair(2, COLOR_CYAN, COLOR_BLACK); + + /* Create items */ + n_choices = ARRAY_SIZE(choices); + my_items = (ITEM **) calloc((size_t) n_choices, sizeof(ITEM *)); + for (i = 0; i < n_choices; ++i) + my_items[i] = new_item(choices[i], choices[i]); + + /* Create menu */ + my_menu = new_menu((ITEM **) my_items); + + /* Create the window to be associated with the menu */ + my_menu_win = newwin(10, 40, 4, 4); + keypad(my_menu_win, TRUE); + + /* Set main window and sub window */ + set_menu_win(my_menu, my_menu_win); + set_menu_sub(my_menu, derwin(my_menu_win, 6, 38, 3, 1)); + set_menu_format(my_menu, 5, 1); + + /* Set menu mark to the string " * " */ + set_menu_mark(my_menu, " * "); + + /* Print a border around the main window and print a title */ + box(my_menu_win, 0, 0); + print_in_middle(my_menu_win, 1, 0, 40, "My Menu", COLOR_PAIR(1)); + mvwaddch(my_menu_win, 2, 0, ACS_LTEE); + mvwhline(my_menu_win, 2, 1, ACS_HLINE, 38); + mvwaddch(my_menu_win, 2, 39, ACS_RTEE); + + /* Post the menu */ + post_menu(my_menu); + wrefresh(my_menu_win); + + attron(COLOR_PAIR(2)); + mvprintw(LINES - 2, 0, + "Use PageUp and PageDown to scroll down or up a page of items"); + mvprintw(LINES - 1, 0, "Arrow Keys to navigate (F1 to Exit)"); + attroff(COLOR_PAIR(2)); + refresh(); + + while ((c = wgetch(my_menu_win)) != KEY_F(1)) { + switch (c) { + case KEY_DOWN: + menu_driver(my_menu, REQ_DOWN_ITEM); + break; + case KEY_UP: + menu_driver(my_menu, REQ_UP_ITEM); + break; + case KEY_NPAGE: + menu_driver(my_menu, REQ_SCR_DPAGE); + break; + case KEY_PPAGE: + menu_driver(my_menu, REQ_SCR_UPAGE); + break; + } wrefresh(my_menu_win); - - attron(COLOR_PAIR(2)); - mvprintw(LINES - 2, 0, "Use PageUp and PageDown to scroll down or up a page of items"); - mvprintw(LINES - 1, 0, "Arrow Keys to navigate (F1 to Exit)"); - attroff(COLOR_PAIR(2)); - refresh(); + } - while((c = wgetch(my_menu_win)) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - case KEY_NPAGE: - menu_driver(my_menu, REQ_SCR_DPAGE); - break; - case KEY_PPAGE: - menu_driver(my_menu, REQ_SCR_UPAGE); - break; - } - wrefresh(my_menu_win); - } - - /* Unpost and free all the memory taken up */ - unpost_menu(my_menu); - free_menu(my_menu); - for(i = 0; i < n_choices; ++i) - free_item(my_items[i]); - endwin(); + /* Unpost and free all the memory taken up */ + unpost_menu(my_menu); + free_menu(my_menu); + for (i = 0; i < n_choices; ++i) + free_item(my_items[i]); + endwin(); } -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); +void +print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color) +{ + int length, x, y; + float temp; + + if (win == NULL) + win = stdscr; + getyx(win, y, x); + if (startx != 0) + x = startx; + if (starty != 0) + y = starty; + if (width == 0) + width = 80; + + length = (int) strlen(string); + temp = (float) (width - length) / 2; + x = startx + (int) temp; + wattron(win, color); + mvwprintw(win, y, x, "%s", string); + wattroff(win, color); + refresh(); }</span></pre> </div> @@ -4785,96 +4904,99 @@ void print_in_middle(WINDOW *win, int starty, int startx, int width, char *strin #define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) #define CTRLD 4 -char *choices[] = { - "Choice 1", "Choice 2", "Choice 3", "Choice 4", "Choice 5", - "Choice 6", "Choice 7", "Choice 8", "Choice 9", "Choice 10", - "Choice 11", "Choice 12", "Choice 13", "Choice 14", "Choice 15", - "Choice 16", "Choice 17", "Choice 18", "Choice 19", "Choice 20", - "Exit", - (char *)NULL, - }; - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - WINDOW *my_menu_win; - int n_choices, i; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_CYAN, COLOR_BLACK); - - /* Create items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - - /* Create menu */ - my_menu = new_menu((ITEM **)my_items); - - /* Set menu option not to show the description */ - menu_opts_off(my_menu, O_SHOWDESC); - - /* Create the window to be associated with the menu */ - my_menu_win = newwin(10, 70, 4, 4); - keypad(my_menu_win, TRUE); - - /* Set main window and sub window */ - set_menu_win(my_menu, my_menu_win); - set_menu_sub(my_menu, derwin(my_menu_win, 6, 68, 3, 1)); - set_menu_format(my_menu, 5, 3); - set_menu_mark(my_menu, " * "); - - /* Print a border around the main window and print a title */ - box(my_menu_win, 0, 0); - - attron(COLOR_PAIR(2)); - mvprintw(LINES - 3, 0, "Use PageUp and PageDown to scroll"); - mvprintw(LINES - 2, 0, "Use Arrow Keys to navigate (F1 to Exit)"); - attroff(COLOR_PAIR(2)); - refresh(); +const char *choices[] = +{ + "Choice 1", "Choice 2", "Choice 3", "Choice 4", "Choice 5", + "Choice 6", "Choice 7", "Choice 8", "Choice 9", "Choice 10", + "Choice 11", "Choice 12", "Choice 13", "Choice 14", "Choice 15", + "Choice 16", "Choice 17", "Choice 18", "Choice 19", "Choice 20", + "Exit", + (char *) NULL, +}; + +int +main(void) +{ + ITEM **my_items; + int c; + MENU *my_menu; + WINDOW *my_menu_win; + int n_choices, i; + + /* Initialize curses */ + initscr(); + start_color(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + init_pair(1, COLOR_RED, COLOR_BLACK); + init_pair(2, COLOR_CYAN, COLOR_BLACK); + + /* Create items */ + n_choices = ARRAY_SIZE(choices); + my_items = (ITEM **) calloc((size_t) n_choices, sizeof(ITEM *)); + for (i = 0; i < n_choices; ++i) + my_items[i] = new_item(choices[i], choices[i]); + + /* Create menu */ + my_menu = new_menu((ITEM **) my_items); + + /* Set menu option not to show the description */ + menu_opts_off(my_menu, O_SHOWDESC); + + /* Create the window to be associated with the menu */ + my_menu_win = newwin(10, 70, 4, 4); + keypad(my_menu_win, TRUE); + + /* Set main window and sub window */ + set_menu_win(my_menu, my_menu_win); + set_menu_sub(my_menu, derwin(my_menu_win, 6, 68, 3, 1)); + set_menu_format(my_menu, 5, 3); + set_menu_mark(my_menu, " * "); + + /* Print a border around the main window and print a title */ + box(my_menu_win, 0, 0); + + attron(COLOR_PAIR(2)); + mvprintw(LINES - 3, 0, "Use PageUp and PageDown to scroll"); + mvprintw(LINES - 2, 0, "Use Arrow Keys to navigate (F1 to Exit)"); + attroff(COLOR_PAIR(2)); + refresh(); - /* Post the menu */ - post_menu(my_menu); + /* Post the menu */ + post_menu(my_menu); + wrefresh(my_menu_win); + + while ((c = wgetch(my_menu_win)) != KEY_F(1)) { + switch (c) { + case KEY_DOWN: + menu_driver(my_menu, REQ_DOWN_ITEM); + break; + case KEY_UP: + menu_driver(my_menu, REQ_UP_ITEM); + break; + case KEY_LEFT: + menu_driver(my_menu, REQ_LEFT_ITEM); + break; + case KEY_RIGHT: + menu_driver(my_menu, REQ_RIGHT_ITEM); + break; + case KEY_NPAGE: + menu_driver(my_menu, REQ_SCR_DPAGE); + break; + case KEY_PPAGE: + menu_driver(my_menu, REQ_SCR_UPAGE); + break; + } wrefresh(my_menu_win); - - while((c = wgetch(my_menu_win)) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - case KEY_LEFT: - menu_driver(my_menu, REQ_LEFT_ITEM); - break; - case KEY_RIGHT: - menu_driver(my_menu, REQ_RIGHT_ITEM); - break; - case KEY_NPAGE: - menu_driver(my_menu, REQ_SCR_DPAGE); - break; - case KEY_PPAGE: - menu_driver(my_menu, REQ_SCR_UPAGE); - break; - } - wrefresh(my_menu_win); - } - - /* Unpost and free all the memory taken up */ - unpost_menu(my_menu); - free_menu(my_menu); - for(i = 0; i < n_choices; ++i) - free_item(my_items[i]); - endwin(); + } + + /* Unpost and free all the memory taken up */ + unpost_menu(my_menu); + free_menu(my_menu); + for (i = 0; i < n_choices; ++i) + free_item(my_items[i]); + endwin(); }</span></pre> </div> @@ -4940,84 +5062,87 @@ int main() #define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) #define CTRLD 4 -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Choice 5", - "Choice 6", - "Choice 7", - "Exit", - }; - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - int n_choices, i; - ITEM *cur_item; - - /* Initialize curses */ - initscr(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - my_items[n_choices] = (ITEM *)NULL; - - my_menu = new_menu((ITEM **)my_items); - - /* Make the menu multi valued */ - menu_opts_off(my_menu, O_ONEVALUE); - - mvprintw(LINES - 3, 0, "Use <SPACE> to select or unselect an item."); - mvprintw(LINES - 2, 0, "<ENTER> to see presently selected items(F1 to Exit)"); - post_menu(my_menu); - refresh(); +const char *choices[] = +{ + "Choice 1", + "Choice 2", + "Choice 3", + "Choice 4", + "Choice 5", + "Choice 6", + "Choice 7", + "Exit", +}; + +int +main(void) +{ + ITEM **my_items; + int c; + MENU *my_menu; + int n_choices, i; + + /* Initialize curses */ + initscr(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + + /* Initialize items */ + n_choices = ARRAY_SIZE(choices); + my_items = (ITEM **) calloc((size_t) (n_choices + 1), sizeof(ITEM *)); + for (i = 0; i < n_choices; ++i) + my_items[i] = new_item(choices[i], choices[i]); + my_items[n_choices] = (ITEM *) NULL; + + my_menu = new_menu((ITEM **) my_items); + + /* Make the menu multi valued */ + menu_opts_off(my_menu, O_ONEVALUE); + + mvprintw(LINES - 3, 0, "Use <SPACE> to select or unselect an item."); + mvprintw(LINES - 2, 0, + "<ENTER> to see presently selected items(F1 to Exit)"); + post_menu(my_menu); + refresh(); - while((c = getch()) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - case ' ': - menu_driver(my_menu, REQ_TOGGLE_ITEM); - break; - case 10: /* Enter */ - { char temp[200]; - ITEM **items; - - items = menu_items(my_menu); - temp[0] = '\0'; - for(i = 0; i < item_count(my_menu); ++i) - if(item_value(items[i]) == TRUE) - { strcat(temp, item_name(items[i])); - strcat(temp, " "); - } - move(20, 0); - clrtoeol(); - mvprintw(20, 0, temp); - refresh(); - } - break; - } - } + while ((c = getch()) != KEY_F(1)) { + switch (c) { + case KEY_DOWN: + menu_driver(my_menu, REQ_DOWN_ITEM); + break; + case KEY_UP: + menu_driver(my_menu, REQ_UP_ITEM); + break; + case ' ': + menu_driver(my_menu, REQ_TOGGLE_ITEM); + break; + case 10: /* Enter */ + { + char temp[200]; + ITEM **items; + + items = menu_items(my_menu); + temp[0] = '\0'; + for (i = 0; i < item_count(my_menu); ++i) + if (item_value(items[i]) == TRUE) { + strcat(temp, item_name(items[i])); + strcat(temp, " "); + } + move(20, 0); + clrtoeol(); + mvaddstr(20, 0, temp); + refresh(); + } + break; + } + } - free_item(my_items[0]); - free_item(my_items[1]); - free_menu(my_menu); - endwin(); -} - </span></pre> + free_item(my_items[0]); + free_item(my_items[1]); + free_menu(my_menu); + endwin(); +}</span></pre> </div> <p>Whew, A lot of new functions. Let's take them one after @@ -5077,81 +5202,82 @@ int main() #define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) #define CTRLD 4 -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Choice 5", - "Choice 6", - "Choice 7", - "Exit", - }; - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - int n_choices, i; - ITEM *cur_item; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_MAGENTA, COLOR_BLACK); - - /* Initialize items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - my_items[i] = new_item(choices[i], choices[i]); - my_items[n_choices] = (ITEM *)NULL; - item_opts_off(my_items[3], O_SELECTABLE); - item_opts_off(my_items[6], O_SELECTABLE); - - /* Create menu */ - my_menu = new_menu((ITEM **)my_items); - - /* Set fore ground and back ground of the menu */ - set_menu_fore(my_menu, COLOR_PAIR(1) | A_REVERSE); - set_menu_back(my_menu, COLOR_PAIR(2)); - set_menu_grey(my_menu, COLOR_PAIR(3)); - - /* Post the menu */ - mvprintw(LINES - 3, 0, "Press <ENTER> to see the option selected"); - mvprintw(LINES - 2, 0, "Up and Down arrow keys to navigate (F1 to Exit)"); - post_menu(my_menu); - refresh(); +const char *choices[] = +{ + "Choice 1", + "Choice 2", + "Choice 3", + "Choice 4", + "Choice 5", + "Choice 6", + "Choice 7", + "Exit", +}; + +int +main(void) +{ + ITEM **my_items; + int c; + MENU *my_menu; + int n_choices, i; + + /* Initialize curses */ + initscr(); + start_color(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + init_pair(1, COLOR_RED, COLOR_BLACK); + init_pair(2, COLOR_GREEN, COLOR_BLACK); + init_pair(3, COLOR_MAGENTA, COLOR_BLACK); + + /* Initialize items */ + n_choices = ARRAY_SIZE(choices); + my_items = (ITEM **) calloc((size_t) (n_choices + 1), sizeof(ITEM *)); + for (i = 0; i < n_choices; ++i) + my_items[i] = new_item(choices[i], choices[i]); + my_items[n_choices] = (ITEM *) NULL; + item_opts_off(my_items[3], O_SELECTABLE); + item_opts_off(my_items[6], O_SELECTABLE); + + /* Create menu */ + my_menu = new_menu((ITEM **) my_items); + + /* Set fore ground and back ground of the menu */ + set_menu_fore(my_menu, COLOR_PAIR(1) | A_REVERSE); + set_menu_back(my_menu, COLOR_PAIR(2)); + set_menu_grey(my_menu, COLOR_PAIR(3)); + + /* Post the menu */ + mvprintw(LINES - 3, 0, "Press <ENTER> to see the option selected"); + mvprintw(LINES - 2, 0, "Up and Down arrow keys to navigate (F1 to Exit)"); + post_menu(my_menu); + refresh(); - while((c = getch()) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - case 10: /* Enter */ - move(20, 0); - clrtoeol(); - mvprintw(20, 0, "Item selected is : %s", - item_name(current_item(my_menu))); - pos_menu_cursor(my_menu); - break; - } - } - unpost_menu(my_menu); - for(i = 0; i < n_choices; ++i) - free_item(my_items[i]); - free_menu(my_menu); - endwin(); -} - </span></pre> + while ((c = getch()) != KEY_F(1)) { + switch (c) { + case KEY_DOWN: + menu_driver(my_menu, REQ_DOWN_ITEM); + break; + case KEY_UP: + menu_driver(my_menu, REQ_UP_ITEM); + break; + case 10: /* Enter */ + move(20, 0); + clrtoeol(); + mvprintw(20, 0, "Item selected is : %s", + item_name(current_item(my_menu))); + pos_menu_cursor(my_menu); + break; + } + } + unpost_menu(my_menu); + for (i = 0; i < n_choices; ++i) + free_item(my_items[i]); + free_menu(my_menu); + endwin(); +}</span></pre> </div> </div> @@ -5181,87 +5307,99 @@ int main() #define ARRAY_SIZE(a) (sizeof(a) / sizeof(a[0])) #define CTRLD 4 -char *choices[] = { - "Choice 1", - "Choice 2", - "Choice 3", - "Choice 4", - "Choice 5", - "Choice 6", - "Choice 7", - "Exit", - }; -void func(char *name); - -int main() -{ ITEM **my_items; - int c; - MENU *my_menu; - int n_choices, i; - ITEM *cur_item; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - init_pair(1, COLOR_RED, COLOR_BLACK); - init_pair(2, COLOR_GREEN, COLOR_BLACK); - init_pair(3, COLOR_MAGENTA, COLOR_BLACK); - - /* Initialize items */ - n_choices = ARRAY_SIZE(choices); - my_items = (ITEM **)calloc(n_choices + 1, sizeof(ITEM *)); - for(i = 0; i < n_choices; ++i) - { my_items[i] = new_item(choices[i], choices[i]); - /* Set the user pointer */ - set_item_userptr(my_items[i], func); - } - my_items[n_choices] = (ITEM *)NULL; +const char *choices[] = +{ + "Choice 1", + "Choice 2", + "Choice 3", + "Choice 4", + "Choice 5", + "Choice 6", + "Choice 7", + "Exit", +}; + +typedef union { + void (*my_func) (const char *); + void *data; +} MY_DATA; + +void func(const char *name); + +int +main(void) +{ + ITEM **my_items; + int c; + MENU *my_menu; + int n_choices, i; + + /* Initialize curses */ + initscr(); + start_color(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + init_pair(1, COLOR_RED, COLOR_BLACK); + init_pair(2, COLOR_GREEN, COLOR_BLACK); + init_pair(3, COLOR_MAGENTA, COLOR_BLACK); + + /* Initialize items */ + n_choices = ARRAY_SIZE(choices); + my_items = (ITEM **) calloc((size_t) (n_choices + 1), sizeof(ITEM *)); + for (i = 0; i < n_choices; ++i) { + MY_DATA data = { func }; + my_items[i] = new_item(choices[i], choices[i]); + /* Set the user pointer */ + set_item_userptr(my_items[i], (void *) &data); + } + my_items[n_choices] = (ITEM *) NULL; - /* Create menu */ - my_menu = new_menu((ITEM **)my_items); + /* Create menu */ + my_menu = new_menu((ITEM **) my_items); - /* Post the menu */ - mvprintw(LINES - 3, 0, "Press <ENTER> to see the option selected"); - mvprintw(LINES - 2, 0, "Up and Down arrow keys to navigate (F1 to Exit)"); - post_menu(my_menu); - refresh(); + /* Post the menu */ + mvprintw(LINES - 3, 0, "Press <ENTER> to see the option selected"); + mvprintw(LINES - 2, 0, "Up and Down arrow keys to navigate (F1 to Exit)"); + post_menu(my_menu); + refresh(); - while((c = getch()) != KEY_F(1)) - { switch(c) - { case KEY_DOWN: - menu_driver(my_menu, REQ_DOWN_ITEM); - break; - case KEY_UP: - menu_driver(my_menu, REQ_UP_ITEM); - break; - case 10: /* Enter */ - { ITEM *cur; - void (*p)(char *); - - cur = current_item(my_menu); - p = item_userptr(cur); - p((char *)item_name(cur)); - pos_menu_cursor(my_menu); - break; - } - break; - } - } - unpost_menu(my_menu); - for(i = 0; i < n_choices; ++i) - free_item(my_items[i]); - free_menu(my_menu); - endwin(); + while ((c = getch()) != KEY_F(1)) { + switch (c) { + case KEY_DOWN: + menu_driver(my_menu, REQ_DOWN_ITEM); + break; + case KEY_UP: + menu_driver(my_menu, REQ_UP_ITEM); + break; + case 10: /* Enter */ + { + ITEM *cur; + const MY_DATA *data; + + cur = current_item(my_menu); + data = item_userptr(cur); + data->my_func(item_name(cur)); + pos_menu_cursor(my_menu); + break; + } + break; + } + } + unpost_menu(my_menu); + for (i = 0; i < n_choices; ++i) + free_item(my_items[i]); + free_menu(my_menu); + endwin(); } -void func(char *name) -{ move(20, 0); - clrtoeol(); - mvprintw(20, 0, "Item selected is : %s", name); -} </span></pre> +void +func(const char *name) +{ + move(20, 0); + clrtoeol(); + mvprintw(20, 0, "Item selected is : %s", name); +}</span></pre> </div> </div> </div> @@ -5384,69 +5522,71 @@ void func(char *name) <pre class="PROGRAMLISTING"><span class= "INLINEMEDIAOBJECT">#include <form.h> -int main() -{ FIELD *field[3]; - FORM *my_form; - int ch; - - /* Initialize curses */ - initscr(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize the fields */ - field[0] = new_field(1, 10, 4, 18, 0, 0); - field[1] = new_field(1, 10, 6, 18, 0, 0); - field[2] = NULL; - - /* Set field options */ - set_field_back(field[0], A_UNDERLINE); /* Print a line for the option */ - field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */ +int +main(void) +{ + FIELD *field[3]; + FORM *my_form; + int ch; + + /* Initialize curses */ + initscr(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + + /* Initialize the fields */ + field[0] = new_field(1, 10, 4, 18, 0, 0); + field[1] = new_field(1, 10, 6, 18, 0, 0); + field[2] = NULL; + + /* Set field options */ + set_field_back(field[0], A_UNDERLINE); /* Print a line for the option */ + field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */ /* Field is filled up */ - set_field_back(field[1], A_UNDERLINE); - field_opts_off(field[1], O_AUTOSKIP); + set_field_back(field[1], A_UNDERLINE); + field_opts_off(field[1], O_AUTOSKIP); - /* Create the form and post it */ - my_form = new_form(field); - post_form(my_form); - refresh(); - - mvprintw(4, 10, "Value 1:"); - mvprintw(6, 10, "Value 2:"); - refresh(); + /* Create the form and post it */ + my_form = new_form(field); + post_form(my_form); + refresh(); - /* Loop through to get user requests */ - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case KEY_DOWN: - /* Go to next field */ - form_driver(my_form, REQ_NEXT_FIELD); - /* Go to the end of the present buffer */ - /* Leaves nicely at the last character */ - form_driver(my_form, REQ_END_LINE); - break; - case KEY_UP: - /* Go to previous field */ - form_driver(my_form, REQ_PREV_FIELD); - form_driver(my_form, REQ_END_LINE); - break; - default: - /* If this is a normal character, it gets */ - /* Printed */ - form_driver(my_form, ch); - break; - } + mvprintw(4, 10, "Value 1:"); + mvprintw(6, 10, "Value 2:"); + refresh(); + + /* Loop through to get user requests */ + while ((ch = getch()) != KEY_F(1)) { + switch (ch) { + case KEY_DOWN: + /* Go to next field */ + form_driver(my_form, REQ_NEXT_FIELD); + /* Go to the end of the present buffer */ + /* Leaves nicely at the last character */ + form_driver(my_form, REQ_END_LINE); + break; + case KEY_UP: + /* Go to previous field */ + form_driver(my_form, REQ_PREV_FIELD); + form_driver(my_form, REQ_END_LINE); + break; + default: + /* If this is a normal character, it gets */ + /* Printed */ + form_driver(my_form, ch); + break; } + } - /* Un post form and free the memory */ - unpost_form(my_form); - free_form(my_form); - free_field(field[0]); - free_field(field[1]); + /* Un post form and free the memory */ + unpost_form(my_form); + free_form(my_form); + free_field(field[0]); + free_field(field[1]); - endwin(); - return 0; + endwin(); + return 0; }</span></pre> </div> @@ -5502,7 +5642,7 @@ int main() <pre class= "PROGRAMLISTING">int field_info( FIELD *field, /* field from which to fetch */ - int *height, *int width, /* field size */ + int *height, *int width, /* field size */ int *top, int *left, /* upper left corner */ int *offscreen, /* number of offscreen rows */ int *nbuf); /* number of working buffers */</pre> @@ -5562,21 +5702,21 @@ int main() <pre class= "PROGRAMLISTING"> int set_field_fore(FIELD *field, /* field to alter */ - chtype attr); /* attribute to set */ + chtype attr); /* attribute to set */ chtype field_fore(FIELD *field); /* field to query */ /* returns foreground attribute */ int set_field_back(FIELD *field, /* field to alter */ - chtype attr); /* attribute to set */ + chtype attr); /* attribute to set */ chtype field_back(FIELD *field); /* field to query */ /* returns background attribute */ int set_field_pad(FIELD *field, /* field to alter */ - int pad); /* pad character to set */ + int pad); /* pad character to set */ -chtype field_pad(FIELD *field); /* field to query */ +chtype field_pad(FIELD *field); /* field to query */ /* returns present pad character */ </pre> <p>Though above functions seem quite simple, using colors with set_field_fore() may be frustrating in the @@ -5599,78 +5739,81 @@ chtype field_pad(FIELD *field); /* field to query */ <pre class="PROGRAMLISTING"><span class= "INLINEMEDIAOBJECT">#include <form.h> -int main() -{ FIELD *field[3]; - FORM *my_form; - int ch; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize few color pairs */ - init_pair(1, COLOR_WHITE, COLOR_BLUE); - init_pair(2, COLOR_WHITE, COLOR_BLUE); - - /* Initialize the fields */ - field[0] = new_field(1, 10, 4, 18, 0, 0); - field[1] = new_field(1, 10, 6, 18, 0, 0); - field[2] = NULL; - - /* Set field options */ - set_field_fore(field[0], COLOR_PAIR(1));/* Put the field with blue background */ - set_field_back(field[0], COLOR_PAIR(2));/* and white foreground (characters */ +int +main(void) +{ + FIELD *field[3]; + FORM *my_form; + int ch; + + /* Initialize curses */ + initscr(); + start_color(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + + /* Initialize few color pairs */ + init_pair(1, COLOR_WHITE, COLOR_BLUE); + init_pair(2, COLOR_WHITE, COLOR_BLUE); + + /* Initialize the fields */ + field[0] = new_field(1, 10, 4, 18, 0, 0); + field[1] = new_field(1, 10, 6, 18, 0, 0); + field[2] = NULL; + + /* Set field options */ + set_field_fore(field[0], COLOR_PAIR(1)); /* Put the field with blue background */ + set_field_back(field[0], COLOR_PAIR(2)); /* and white foreground (characters */ /* are printed in white */ - field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */ + field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */ /* Field is filled up */ - set_field_back(field[1], A_UNDERLINE); - field_opts_off(field[1], O_AUTOSKIP); + set_field_back(field[1], A_UNDERLINE); + field_opts_off(field[1], O_AUTOSKIP); - /* Create the form and post it */ - my_form = new_form(field); - post_form(my_form); - refresh(); - - set_current_field(my_form, field[0]); /* Set focus to the colored field */ - mvprintw(4, 10, "Value 1:"); - mvprintw(6, 10, "Value 2:"); - mvprintw(LINES - 2, 0, "Use UP, DOWN arrow keys to switch between fields"); - refresh(); + /* Create the form and post it */ + my_form = new_form(field); + post_form(my_form); + refresh(); - /* Loop through to get user requests */ - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case KEY_DOWN: - /* Go to next field */ - form_driver(my_form, REQ_NEXT_FIELD); - /* Go to the end of the present buffer */ - /* Leaves nicely at the last character */ - form_driver(my_form, REQ_END_LINE); - break; - case KEY_UP: - /* Go to previous field */ - form_driver(my_form, REQ_PREV_FIELD); - form_driver(my_form, REQ_END_LINE); - break; - default: - /* If this is a normal character, it gets */ - /* Printed */ - form_driver(my_form, ch); - break; - } + set_current_field(my_form, field[0]); /* Set focus to the colored field */ + mvprintw(4, 10, "Value 1:"); + mvprintw(6, 10, "Value 2:"); + mvprintw(LINES - 2, 0, + "Use UP, DOWN arrow keys to switch between fields"); + refresh(); + + /* Loop through to get user requests */ + while ((ch = getch()) != KEY_F(1)) { + switch (ch) { + case KEY_DOWN: + /* Go to next field */ + form_driver(my_form, REQ_NEXT_FIELD); + /* Go to the end of the present buffer */ + /* Leaves nicely at the last character */ + form_driver(my_form, REQ_END_LINE); + break; + case KEY_UP: + /* Go to previous field */ + form_driver(my_form, REQ_PREV_FIELD); + form_driver(my_form, REQ_END_LINE); + break; + default: + /* If this is a normal character, it gets */ + /* Printed */ + form_driver(my_form, ch); + break; } + } - /* Un post form and free the memory */ - unpost_form(my_form); - free_form(my_form); - free_field(field[0]); - free_field(field[1]); + /* Un post form and free the memory */ + unpost_form(my_form); + free_form(my_form); + free_field(field[0]); + free_field(field[1]); - endwin(); - return 0; + endwin(); + return 0; }</span></pre> </div> @@ -5694,15 +5837,15 @@ int main() <pre class= "PROGRAMLISTING">int set_field_opts(FIELD *field, /* field to alter */ - int attr); /* attribute to set */ + int attr); /* attribute to set */ int field_opts_on(FIELD *field, /* field to alter */ - int attr); /* attributes to turn on */ + int attr); /* attributes to turn on */ int field_opts_off(FIELD *field, /* field to alter */ - int attr); /* attributes to turn off */ + int attr); /* attributes to turn off */ -int field_opts(FIELD *field); /* field to query */ </pre> +int field_opts(FIELD *field); /* field to query */</pre> <p>The function set_field_opts() can be used to directly set attributes of a field or you can choose to switch a few attributes on and off with field_opts_on() and @@ -5842,73 +5985,75 @@ int field_opts(FIELD *field); /* field to query */ </pre> #define N_FIELDS 3 -int main() -{ FIELD *field[N_FIELDS]; - FORM *my_form; - int ch, i; - - /* Initialize curses */ - initscr(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize the fields */ - for(i = 0; i < N_FIELDS - 1; ++i) - field[i] = new_field(1, WIDTH, STARTY + i * 2, STARTX, 0, 0); - field[N_FIELDS - 1] = NULL; - - /* Set field options */ - set_field_back(field[1], A_UNDERLINE); /* Print a line for the option */ - - field_opts_off(field[0], O_ACTIVE); /* This field is a static label */ - field_opts_off(field[1], O_PUBLIC); /* This filed is like a password field*/ - field_opts_off(field[1], O_AUTOSKIP); /* To avoid entering the same field */ - /* after last character is entered */ - - /* Create the form and post it */ - my_form = new_form(field); - post_form(my_form); - refresh(); - - set_field_just(field[0], JUSTIFY_CENTER); /* Center Justification */ - set_field_buffer(field[0], 0, "This is a static Field"); - /* Initialize the field */ - mvprintw(STARTY, STARTX - 10, "Field 1:"); - mvprintw(STARTY + 2, STARTX - 10, "Field 2:"); - refresh(); +int +main(void) +{ + FIELD *field[N_FIELDS]; + FORM *my_form; + int ch, i; + + /* Initialize curses */ + initscr(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + + /* Initialize the fields */ + for (i = 0; i < N_FIELDS - 1; ++i) + field[i] = new_field(1, WIDTH, STARTY + i * 2, STARTX, 0, 0); + field[N_FIELDS - 1] = NULL; + + /* Set field options */ + set_field_back(field[1], A_UNDERLINE); /* Print a line for the option */ + + field_opts_off(field[0], O_ACTIVE); /* This field is a static label */ + field_opts_off(field[1], O_PUBLIC); /* This filed is like a password field */ + field_opts_off(field[1], O_AUTOSKIP); /* To avoid entering the same field */ + /* after last character is entered */ + + /* Create the form and post it */ + my_form = new_form(field); + post_form(my_form); + refresh(); - /* Loop through to get user requests */ - while((ch = getch()) != KEY_F(1)) - { switch(ch) - { case KEY_DOWN: - /* Go to next field */ - form_driver(my_form, REQ_NEXT_FIELD); - /* Go to the end of the present buffer */ - /* Leaves nicely at the last character */ - form_driver(my_form, REQ_END_LINE); - break; - case KEY_UP: - /* Go to previous field */ - form_driver(my_form, REQ_PREV_FIELD); - form_driver(my_form, REQ_END_LINE); - break; - default: - /* If this is a normal character, it gets */ - /* Printed */ - form_driver(my_form, ch); - break; - } + set_field_just(field[0], JUSTIFY_CENTER); /* Center Justification */ + set_field_buffer(field[0], 0, "This is a static Field"); + /* Initialize the field */ + mvprintw(STARTY, STARTX - 10, "Field 1:"); + mvprintw(STARTY + 2, STARTX - 10, "Field 2:"); + refresh(); + + /* Loop through to get user requests */ + while ((ch = getch()) != KEY_F(1)) { + switch (ch) { + case KEY_DOWN: + /* Go to next field */ + form_driver(my_form, REQ_NEXT_FIELD); + /* Go to the end of the present buffer */ + /* Leaves nicely at the last character */ + form_driver(my_form, REQ_END_LINE); + break; + case KEY_UP: + /* Go to previous field */ + form_driver(my_form, REQ_PREV_FIELD); + form_driver(my_form, REQ_END_LINE); + break; + default: + /* If this is a normal character, it gets */ + /* Printed */ + form_driver(my_form, ch); + break; } + } - /* Un post form and free the memory */ - unpost_form(my_form); - free_form(my_form); - free_field(field[0]); - free_field(field[1]); + /* Un post form and free the memory */ + unpost_form(my_form); + free_form(my_form); + free_field(field[0]); + free_field(field[1]); - endwin(); - return 0; + endwin(); + return 0; }</span></pre> </div> @@ -5961,7 +6106,7 @@ int field_status(FIELD *field); /* fetch status of field */</pre> pointer.</p> <pre class= - "PROGRAMLISTING">int set_field_userptr(FIELD *field, + "PROGRAMLISTING">int set_field_userptr(FIELD *field, char *userptr); /* the user pointer you wish to associate */ /* with the field */ @@ -6132,115 +6277,122 @@ proper attributes of a dynamically growable field. "INLINEMEDIAOBJECT">#include <string.h> #include <form.h> -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color); +void print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color); -int main() +int +main(void) { - FIELD *field[3]; - FORM *my_form; - WINDOW *my_form_win; - int ch, rows, cols; - - /* Initialize curses */ - initscr(); - start_color(); - cbreak(); - noecho(); - keypad(stdscr, TRUE); - - /* Initialize few color pairs */ - init_pair(1, COLOR_RED, COLOR_BLACK); - - /* Initialize the fields */ - field[0] = new_field(1, 10, 6, 1, 0, 0); - field[1] = new_field(1, 10, 8, 1, 0, 0); - field[2] = NULL; - - /* Set field options */ - set_field_back(field[0], A_UNDERLINE); - field_opts_off(field[0], O_AUTOSKIP); /* Don't go to next field when this */ - /* Field is filled up */ - set_field_back(field[1], A_UNDERLINE); - field_opts_off(field[1], O_AUTOSKIP); - - /* Create the form and post it */ - my_form = new_form(field); - - /* Calculate the area required for the form */ - scale_form(my_form, &rows, &cols); - - /* Create the window to be associated with the form */ - my_form_win = newwin(rows + 4, cols + 4, 4, 4); - keypad(my_form_win, TRUE); - - /* Set main window and sub window */ - set_form_win(my_form, my_form_win); - set_form_sub(my_form, derwin(my_form_win, rows, cols, 2, 2)); - - /* Print a border around the main window and print a title */ - box(my_form_win, 0, 0); - print_in_middle(my_form_win, 1, 0, cols + 4, "My Form", COLOR_PAIR(1)); - - post_form(my_form); - wrefresh(my_form_win); - - mvprintw(LINES - 2, 0, "Use UP, DOWN arrow keys to switch between fields"); - refresh(); + FIELD *field[3]; + FORM *my_form; + WINDOW *my_form_win; + int ch, rows, cols; + + /* Initialize curses */ + initscr(); + start_color(); + cbreak(); + noecho(); + keypad(stdscr, TRUE); + + /* Initialize few color pairs */ + init_pair(1, COLOR_RED, COLOR_BLACK); + + /* Initialize the fields */ + field[0] = new_field(1, 10, 6, 1, 0, 0); + field[1] = new_field(1, 10, 8, 1, 0, 0); + field[2] = NULL; + + /* Set field options */ + set_field_back(field[0], A_UNDERLINE); + field_opts_off(field[0], O_AUTOSKIP); + /* Don't go to next field when this */ + /* Field is filled up */ + set_field_back(field[1], A_UNDERLINE); + field_opts_off(field[1], O_AUTOSKIP); + + /* Create the form and post it */ + my_form = new_form(field); + + /* Calculate the area required for the form */ + scale_form(my_form, &rows, &cols); + + /* Create the window to be associated with the form */ + my_form_win = newwin(rows + 4, cols + 4, 4, 4); + keypad(my_form_win, TRUE); + + /* Set main window and sub window */ + set_form_win(my_form, my_form_win); + set_form_sub(my_form, derwin(my_form_win, rows, cols, 2, 2)); + + /* Print a border around the main window and print a title */ + box(my_form_win, 0, 0); + print_in_middle(my_form_win, 1, 0, cols + 4, "My Form", COLOR_PAIR(1)); + + post_form(my_form); + wrefresh(my_form_win); + + mvprintw(LINES - 2, 0, + "Use UP, DOWN arrow keys to switch between fields"); + refresh(); - /* Loop through to get user requests */ - while((ch = wgetch(my_form_win)) != KEY_F(1)) - { switch(ch) - { case KEY_DOWN: - /* Go to next field */ - form_driver(my_form, REQ_NEXT_FIELD); - /* Go to the end of the present buffer */ - /* Leaves nicely at the last character */ - form_driver(my_form, REQ_END_LINE); - break; - case KEY_UP: - /* Go to previous field */ - form_driver(my_form, REQ_PREV_FIELD); - form_driver(my_form, REQ_END_LINE); - break; - default: - /* If this is a normal character, it gets */ - /* Printed */ - form_driver(my_form, ch); - break; - } + /* Loop through to get user requests */ + while ((ch = wgetch(my_form_win)) != KEY_F(1)) { + switch (ch) { + case KEY_DOWN: + /* Go to next field */ + form_driver(my_form, REQ_NEXT_FIELD); + /* Go to the end of the present buffer */ + /* Leaves nicely at the last character */ + form_driver(my_form, REQ_END_LINE); + break; + case KEY_UP: + /* Go to previous field */ + form_driver(my_form, REQ_PREV_FIELD); + form_driver(my_form, REQ_END_LINE); + break; + default: + /* If this is a normal character, it gets */ + /* Printed */ + form_driver(my_form, ch); + break; } + } - /* Un post form and free the memory */ - unpost_form(my_form); - free_form(my_form); - free_field(field[0]); - free_field(field[1]); + /* Un post form and free the memory */ + unpost_form(my_form); + free_form(my_form); + free_field(field[0]); + free_field(field[1]); - endwin(); - return 0; + endwin(); + return 0; } -void print_in_middle(WINDOW *win, int starty, int startx, int width, char *string, chtype color) -{ int length, x, y; - float temp; - - if(win == NULL) - win = stdscr; - getyx(win, y, x); - if(startx != 0) - x = startx; - if(starty != 0) - y = starty; - if(width == 0) - width = 80; - - length = strlen(string); - temp = (width - length)/ 2; - x = startx + (int)temp; - wattron(win, color); - mvwprintw(win, y, x, "%s", string); - wattroff(win, color); - refresh(); +void +print_in_middle(WINDOW *win, int starty, int startx, + int width, const char *string, chtype color) +{ + int length, x, y; + float temp; + + if (win == NULL) + win = stdscr; + getyx(win, y, x); + if (startx != 0) + x = startx; + if (starty != 0) + y = starty; + if (width == 0) + width = 80; + + length = (int) strlen(string); + temp = (float) (width - length) / 2; + x = startx + (int) temp; + wattron(win, color); + mvwprintw(win, y, x, "%s", string); + wattroff(win, color); + refresh(); }</span></pre> </div> </div> @@ -6290,8 +6442,8 @@ set, the validation type for a field can be queried with can also specify custom validation, though it is a bit tricky and cumbersome.</p> - <h1 class="BRIDGEHEAD"><a name="AEN1074" id= - "AEN1074"></a>TYPE_ALPHA</h1> + <h1 class="BRIDGEHEAD"><a name="AEN1095" id= + "AEN1095"></a>TYPE_ALPHA</h1> <p>This field type accepts alphabetic data; no blanks, no digits, no special characters (this is checked at @@ -6308,8 +6460,8 @@ set, the validation type for a field can be queried with width, the validation check will always fail. A minimum width of zero makes field completion optional.</p> - <h1 class="BRIDGEHEAD"><a name="AEN1078" id= - "AEN1078"></a>TYPE_ALNUM</h1> + <h1 class="BRIDGEHEAD"><a name="AEN1099" id= + "AEN1099"></a>TYPE_ALNUM</h1> <p>This field type accepts alphabetic data and digits; no blanks, no special characters (this is checked at @@ -6325,8 +6477,8 @@ set, the validation type for a field can be queried with validation check will always fail. A minimum width of zero makes field completion optional.</p> - <h1 class="BRIDGEHEAD"><a name="AEN1082" id= - "AEN1082"></a>TYPE_ENUM</h1> + <h1 class="BRIDGEHEAD"><a name="AEN1103" id= + "AEN1103"></a>TYPE_ENUM</h1> <p>This type allows you to restrict a field's values to be among a specified set of string values (for example, the @@ -6358,8 +6510,8 @@ set, the validation type for a field can be queried with <p>The REQ_NEXT_CHOICE and REQ_PREV_CHOICE input requests can be particularly useful with these fields.</p> - <h1 class="BRIDGEHEAD"><a name="AEN1089" id= - "AEN1089"></a>TYPE_INTEGER</h1> + <h1 class="BRIDGEHEAD"><a name="AEN1110" id= + "AEN1110"></a>TYPE_INTEGER</h1> <p>This field type accepts an integer. It is set up as follows:</p> @@ -6381,8 +6533,8 @@ set, the validation type for a field can be queried with <p>A TYPE_INTEGER value buffer can conveniently be interpreted with the C library function atoi(3).</p> - <h1 class="BRIDGEHEAD"><a name="AEN1095" id= - "AEN1095"></a>TYPE_NUMERIC</h1> + <h1 class="BRIDGEHEAD"><a name="AEN1116" id= + "AEN1116"></a>TYPE_NUMERIC</h1> <p>This field type accepts a decimal number. It is set up as follows:</p> @@ -6404,8 +6556,8 @@ set, the validation type for a field can be queried with <p>A TYPE_NUMERIC value buffer can conveniently be interpreted with the C library function atof(3).</p> - <h1 class="BRIDGEHEAD"><a name="AEN1101" id= - "AEN1101"></a>TYPE_REGEXP</h1> + <h1 class="BRIDGEHEAD"><a name="AEN1122" id= + "AEN1122"></a>TYPE_REGEXP</h1> <p>This field type accepts data matching a regular expression. It is set up as follows:</p> @@ -7034,7 +7186,7 @@ set, the validation type for a field can be queried with Alphalist Allows a user to select from a list of words, with the ability to narrow the search list by typing in a few characters of the desired word. -Buttonbox This creates a multiple button widget. +Buttonbox This creates a multiple button widget. Calendar Creates a little simple calendar widget. Dialog Prompts the user with a message, and the user can pick an answer from the buttons provided. @@ -7057,17 +7209,17 @@ Multiple Line Entry A multiple line entry field. Very useful field) Radio List Creates a radio button list. Scale Creates a numeric scale. Used for allowing a user to - pick a numeric value and restrict them to a range of + pick a numeric value and restrict them to a range of values. Scrolling List Creates a scrolling list/menu list. -Scrolling Window Creates a scrolling log file viewer. Can add - information into the window while its running. +Scrolling Window Creates a scrolling log file viewer. Can add + information into the window while its running. A good widget for displaying the progress of something. (akin to a console window) Selection List Creates a multiple option selection list. Slider Akin to the scale widget, this widget provides a visual slide bar to represent the numeric value. -Template Creates a entry field with character sensitive +Template Creates a entry field with character sensitive positions. Used for pre-formatted fields like dates and phone numbers. Viewer This is a file/information viewer. Very useful diff --git a/doc/html/ada/funcs/T.htm b/doc/html/ada/funcs/T.htm index 2534502a5360..acedebee23d0 100644 --- a/doc/html/ada/funcs/T.htm +++ b/doc/html/ada/funcs/T.htm @@ -20,8 +20,8 @@ <li><a href="../terminal_interface-curses-termcap__adb.htm#ref_90_16" target="main">tgetnum</a> <li><a href="../terminal_interface-curses-termcap__adb.htm#ref_109_16" target="main">tgetstr - terminal_interface-curses-termcap.adb:109</a> <li><a href="../terminal_interface-curses-termcap__adb.htm#ref_130_16" target="main">tgetstr - terminal_interface-curses-termcap.adb:130</a> -<li><a href="../terminal_interface-curses-termcap__ads.htm#ref_54_13" target="main">TGoto</a> <li><a href="../terminal_interface-curses-termcap__adb.htm#ref_152_16" target="main">tgoto</a> +<li><a href="../terminal_interface-curses-termcap__ads.htm#ref_54_13" target="main">TGoto</a> <li><a href="../terminal_interface-curses-terminfo__adb.htm#ref_70_16" target="main">tigetflag</a> <li><a href="../terminal_interface-curses-terminfo__adb.htm#ref_88_16" target="main">tigetstr - terminal_interface-curses-terminfo.adb:88</a> <li><a href="../terminal_interface-curses-terminfo__adb.htm#ref_109_16" target="main">tigetstr - terminal_interface-curses-terminfo.adb:109</a> diff --git a/doc/html/ada/terminal_interface-curses-forms__adb.htm b/doc/html/ada/terminal_interface-curses-forms__adb.htm index 3f22b40dac6f..f4fb87c9dddc 100644 --- a/doc/html/ada/terminal_interface-curses-forms__adb.htm +++ b/doc/html/ada/terminal_interface-curses-forms__adb.htm @@ -24,7 +24,7 @@ <span class="comment"><em>-- B O D Y --</em></span> <span class="comment"><em>-- --</em></span> <span class="comment"><em>------------------------------------------------------------------------------</em></span> -<span class="comment"><em>-- Copyright 2020 Thomas E. Dickey --</em></span> +<span class="comment"><em>-- Copyright 2020,2025 Thomas E. Dickey --</em></span> <span class="comment"><em>-- Copyright 1999-2011,2014 Free Software Foundation, Inc. --</em></span> <span class="comment"><em>-- --</em></span> <span class="comment"><em>-- Permission is hereby granted, free of charge, to any person obtaining a --</em></span> @@ -53,8 +53,8 @@ <span class="comment"><em>------------------------------------------------------------------------------</em></span> <span class="comment"><em>-- Author: Juergen Pfeifer, 1996</em></span> <span class="comment"><em>-- Version Control:</em></span> -<span class="comment"><em>-- @Revision: 1.33 @</em></span> -<span class="comment"><em>-- @Date: 2020/02/02 23:34:34 @</em></span> +<span class="comment"><em>-- @Revision: 1.34 @</em></span> +<span class="comment"><em>-- @Date: 2025/01/24 20:39:23 @</em></span> <span class="comment"><em>-- Binding Version 01.00</em></span> <span class="comment"><em>------------------------------------------------------------------------------</em></span> <b>with</b> Ada.Unchecked_Deallocation; @@ -1023,7 +1023,7 @@ (Field_Array, <a href="terminal_interface-curses-forms__ads.htm#ref_136_9">Field_Array_Access</a>); <b>begin</b> <b>if</b> <a href="terminal_interface-curses-forms__ads.htm#ref_138_20">FA</a> /= <b>null</b> <b>and</b> <b>then</b> <a href="terminal_interface-curses-forms__ads.htm#ref_139_20">Free_Fields</a> <b>then</b> - <b>for</b> <span class="symbol"><a name="ref_1009_14">I</a></span> <b>in</b> <a href="terminal_interface-curses-forms__ads.htm#ref_138_20">FA</a>'First .. (<a href="terminal_interface-curses-forms__ads.htm#ref_138_20">FA</a>'Last - 1) <b>loop</b> + <b>for</b> <span class="symbol"><a name="ref_1009_14">I</a></span> <b>in</b> <a href="terminal_interface-curses-forms__ads.htm#ref_138_20">FA</a>'First .. <a href="terminal_interface-curses-forms__ads.htm#ref_138_20">FA</a>'Last - 1 <b>loop</b> <b>if</b> <a href="terminal_interface-curses-forms__ads.htm#ref_138_20">FA</a>.<b>all</b> (<a href="terminal_interface-curses-forms__adb.htm#ref_1009_14">I</a>) /= <a href="terminal_interface-curses-forms__ads.htm#ref_55_4">Null_Field</a> <b>then</b> <a href="terminal_interface-curses-forms__ads.htm#ref_317_14">Delete</a> (<a href="terminal_interface-curses-forms__ads.htm#ref_138_20">FA</a>.<b>all</b> (<a href="terminal_interface-curses-forms__adb.htm#ref_1009_14">I</a>)); <b>end</b> <b>if</b>; diff --git a/doc/html/ada/terminal_interface-curses-menus__adb.htm b/doc/html/ada/terminal_interface-curses-menus__adb.htm index 560273380537..e1d9bdf1009e 100644 --- a/doc/html/ada/terminal_interface-curses-menus__adb.htm +++ b/doc/html/ada/terminal_interface-curses-menus__adb.htm @@ -24,7 +24,7 @@ <span class="comment"><em>-- B O D Y --</em></span> <span class="comment"><em>-- --</em></span> <span class="comment"><em>------------------------------------------------------------------------------</em></span> -<span class="comment"><em>-- Copyright 2018,2020 Thomas E. Dickey --</em></span> +<span class="comment"><em>-- Copyright 2018-2020,2025 Thomas E. Dickey --</em></span> <span class="comment"><em>-- Copyright 1999-2011,2014 Free Software Foundation, Inc. --</em></span> <span class="comment"><em>-- --</em></span> <span class="comment"><em>-- Permission is hereby granted, free of charge, to any person obtaining a --</em></span> @@ -53,8 +53,8 @@ <span class="comment"><em>------------------------------------------------------------------------------</em></span> <span class="comment"><em>-- Author: Juergen Pfeifer, 1996</em></span> <span class="comment"><em>-- Version Control:</em></span> -<span class="comment"><em>-- @Revision: 1.34 @</em></span> -<span class="comment"><em>-- @Date: 2020/02/02 23:34:34 @</em></span> +<span class="comment"><em>-- @Revision: 1.35 @</em></span> +<span class="comment"><em>-- @Date: 2025/01/24 20:39:23 @</em></span> <span class="comment"><em>-- Binding Version 01.00</em></span> <span class="comment"><em>------------------------------------------------------------------------------</em></span> <b>with</b> Ada.Unchecked_Deallocation; @@ -895,7 +895,7 @@ (Item_Array, <a href="terminal_interface-curses-menus__ads.htm#ref_177_9">Item_Array_Access</a>); <b>begin</b> <b>if</b> <a href="terminal_interface-curses-menus__ads.htm#ref_179_20">IA</a> /= <b>null</b> <b>and</b> <b>then</b> <a href="terminal_interface-curses-menus__ads.htm#ref_180_20">Free_Items</a> <b>then</b> - <b>for</b> <span class="symbol"><a name="ref_881_14">I</a></span> <b>in</b> <a href="terminal_interface-curses-menus__ads.htm#ref_179_20">IA</a>'First .. (<a href="terminal_interface-curses-menus__ads.htm#ref_179_20">IA</a>'Last - 1) <b>loop</b> + <b>for</b> <span class="symbol"><a name="ref_881_14">I</a></span> <b>in</b> <a href="terminal_interface-curses-menus__ads.htm#ref_179_20">IA</a>'First .. <a href="terminal_interface-curses-menus__ads.htm#ref_179_20">IA</a>'Last - 1 <b>loop</b> <b>if</b> <a href="terminal_interface-curses-menus__ads.htm#ref_179_20">IA</a>.<b>all</b> (<a href="terminal_interface-curses-menus__adb.htm#ref_881_14">I</a>) /= <a href="terminal_interface-curses-menus__ads.htm#ref_58_4">Null_Item</a> <b>then</b> <a href="terminal_interface-curses-menus__ads.htm#ref_202_14">Delete</a> (<a href="terminal_interface-curses-menus__ads.htm#ref_179_20">IA</a>.<b>all</b> (<a href="terminal_interface-curses-menus__adb.htm#ref_881_14">I</a>)); <b>end</b> <b>if</b>; diff --git a/doc/html/ada/terminal_interface-curses-panels-user_data__adb.htm b/doc/html/ada/terminal_interface-curses-panels-user_data__adb.htm index 7270d2c89df7..8fd12a31b1ae 100644 --- a/doc/html/ada/terminal_interface-curses-panels-user_data__adb.htm +++ b/doc/html/ada/terminal_interface-curses-panels-user_data__adb.htm @@ -24,7 +24,7 @@ <span class="comment"><em>-- B O D Y --</em></span> <span class="comment"><em>-- --</em></span> <span class="comment"><em>------------------------------------------------------------------------------</em></span> -<span class="comment"><em>-- Copyright 2020 Thomas E. Dickey --</em></span> +<span class="comment"><em>-- Copyright 2020,2025 Thomas E. Dickey --</em></span> <span class="comment"><em>-- Copyright 1999-2003,2009 Free Software Foundation, Inc. --</em></span> <span class="comment"><em>-- --</em></span> <span class="comment"><em>-- Permission is hereby granted, free of charge, to any person obtaining a --</em></span> @@ -53,7 +53,7 @@ <span class="comment"><em>------------------------------------------------------------------------------</em></span> <span class="comment"><em>-- Author: Juergen Pfeifer, 1996</em></span> <span class="comment"><em>-- Version Control:</em></span> -<span class="comment"><em>-- @Revision: 1.13 @</em></span> +<span class="comment"><em>-- @Revision: 1.14 @</em></span> <span class="comment"><em>-- Binding Version 01.00</em></span> <span class="comment"><em>------------------------------------------------------------------------------</em></span> <b>with</b> <a href="interfac__ads.htm#ref_38_9">Interfaces</a>.C; diff --git a/doc/html/ada/terminal_interface-curses_constants__ads.htm b/doc/html/ada/terminal_interface-curses_constants__ads.htm index 5a10ea48fef9..d3e708a99b35 100644 --- a/doc/html/ada/terminal_interface-curses_constants__ads.htm +++ b/doc/html/ada/terminal_interface-curses_constants__ads.htm @@ -36,8 +36,8 @@ <span class="comment"><em>-- Version of the ncurses library from extensions(3NCURSES)</em></span> <span class="symbol"><a name="ref_21_4">NCURSES_VERSION_MAJOR</a></span> : <b>constant</b> := 6; - <span class="symbol"><a name="ref_22_4">NCURSES_VERSION_MINOR</a></span> : <b>constant</b> := 5; - <span class="symbol"><a name="ref_23_4">Version</a></span> : <b>constant</b> String := "6.5"; + <span class="symbol"><a name="ref_22_4">NCURSES_VERSION_MINOR</a></span> : <b>constant</b> := 6; + <span class="symbol"><a name="ref_23_4">Version</a></span> : <b>constant</b> String := "6.6"; <span class="comment"><em>-- Character non-color attributes from attr(3NCURSES)</em></span> @@ -110,7 +110,7 @@ <span class="symbol"><a name="ref_93_4">E_INVALID_FIELD</a></span> : <b>constant</b> := -13; <span class="symbol"><a name="ref_94_4">E_CURRENT</a></span> : <b>constant</b> := -14; - <span class="comment"><em>-- Input key codes not defined in any ncurses manpage</em></span> + <span class="comment"><em>-- Input key codes not defined in any ncurses man page</em></span> <span class="symbol"><a name="ref_98_4">KEY_MIN</a></span> : <b>constant</b> := 257; <span class="symbol"><a name="ref_99_4">KEY_MAX</a></span> : <b>constant</b> := 511; diff --git a/doc/html/announce.html b/doc/html/announce.html index 2aa03cfab131..483bfe522833 100644 --- a/doc/html/announce.html +++ b/doc/html/announce.html @@ -1,7 +1,7 @@ <!-- - $Id: announce.html,v 1.70 2024/04/27 18:38:45 tom Exp $ + $Id: announce.html,v 1.71 2025/12/30 20:20:20 tom Exp $ **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * * * Permission is hereby granted, free of charge, to any person obtaining a * * copy of this software and associated documentation files (the * @@ -32,7 +32,7 @@ <html> <head> <meta name="generator" content= - "HTML Tidy for HTML5 for Linux version 5.6.0"> + "HTML Tidy for HTML5 for Linux version 5.8.0"> <title>Announcing ncurses 6.5</title> <link rel="author" href="mailto:bug-ncurses@gnu.org"> <meta http-equiv="Content-Type" content= @@ -154,10 +154,10 @@ Notes</a></h2> <p>These notes are for <span class="main-name">ncurses</span> - 6.5, released <strong>April 27, 2024</strong>.</p> + 6.5, released <strong>December 30, 2025</strong>.</p> <p>This release is designed to be source-compatible with - <span class="main-name">ncurses</span> 5.0 through 6.4; providing + <span class="main-name">ncurses</span> 5.0 through 6.5; providing extensions to the application binary interface (ABI). Although the source can still be configured to support the <span class= "main-name">ncurses</span> 5 ABI, the reason for the release is @@ -165,75 +165,130 @@ "main-name">ncurses</span> 6 ABI and the supporting utility programs.</p> - <p>There are, of course, numerous other improvements, listed in - this announcement.</p> + <p>There are numerous other improvements listed in this + announcement.</p> <p>The most <a href="#h3-bug-fixes">important bug-fixes/improvements</a> dealt with robustness issues. The release notes also mention some other bug-fixes, but are focused on new features and improvements to existing features since - <span class="main-name">ncurses</span> 6.4 release.</p> + <span class="main-name">ncurses</span> 6.5 release.</p> <h3><a name="h3-library" id="h3-library">Library improvements</a></h3> - <h4><a name="h4-new-library" id="h4-new-library">New features</a></h4> + <h4><a name="h4-term-driver" id="h4-term-driver">Terminal driver + improvements</a></h4> - <p>These are new features:</p> + <p>This release focuses on improvements to the MinGW/Windows + terminal driver. The terminal driver for MinGW32 was introduced + in <a href="https://invisible-island.net/ncurses/NEWS.html#t20090214">2009</a>. A new + version of the terminal driver to support Windows Terminal was + begun in <a href="https://invisible-island.net/ncurses/NEWS.html#t20200829">2020</a>. + However, there were some differences:</p> <ul> <li> - <p>The low-level terminfo and termcap interfaces are used - both by the higher-level curses library, as well as by many - applications.</p> + <p>Both drivers use <a href= + "https://learn.microsoft.com/en-us/windows/console/console-reference"> + Console API</a>; the later Windows driver also provides for + using character escape sequences.</p> + </li> - <p>The functions which convert parameterized terminal - capability strings for output to the terminal - (<code>tiparm</code> and <code>tparm</code>) analyze the - capability string to determine which parameters are strings - (i.e., addresses), versus numbers (not addresses).</p> + <li> + <p>The MinGW32 driver was designed to imitate POSIX terminal + I/O data types to simplify integration with the existing + sources.</p> - <p>The library's analysis of a capability string may differ - from the calling application's design if environment - variables are used to point to an invalid terminal database. - This is a longstanding problem with <em>all</em> - implementations of terminfo, dating from the early 1980s.</p> + <p>The newer Windows driver did not integrate with the + sources in the same way. In particular, the <a href= + "https://invisible-island.net/ncurses/man/tset.1.html">reset</a> utility was + incomplete.</p> + </li> - <p>Two new functions address this problem: by providing a - function which allows the calling application to tell ncurses - how many string-parameters to expect:</p> + <li> + <p>Windows Terminal support for Console API is incomplete, + lacking mouse support. Additionally, its developers took a + few years to resolve issues with carriage-return versus + line-feed translation.</p> - <ul> - <li><code>tiscan_s</code> helps applications check - formatting capabilities that would be passed to - <code>tiparm_s</code>.</li> + <p>Reflecting on these problems, both MinGW and Windows + drivers are still provided in ncurses through the current + release.</p> + </li> - <li><code>tiparm_s</code> provides applications a way to - tell ncurses what the expected parameters are for a - capability.</li> - </ul> + <li> + <p>The two drivers are similar, but in developing the Windows + driver some renaming and refactoring was done. That resulted + in duplicate source files. This release eliminates the + duplication.</p> </li> + </ul> + <p>These improvements have been made to the terminal driver:</p> + + <ul> <li> - <p>The ncurses library supports a compile-time feature - (enabled with the configure <code>--enable-check-size</code> - option) which simplifies initialization with terminals which - do not negotiate window (screen) size. This is done in - <code>setupterm</code>, by providing for using ANSI - cursor-position report (in user6/user7 terminfo capabilities) - to obtain the screen size if neither environment variables or - ioctl is used.</p> + <p>made <tt>win_driver.c</tt> obsolete in favor of + <tt>win32_driver.c</tt></p> + </li> - <p>The ncurses test-program with options - “<code>-E -T</code>” demonstrates this - feature.</p> + <li> + <p>made <tt>win32_curses.h</tt> obsolete in favor of + <tt>nc_win32.h</tt></p> </li> - <li>add functions to query tty-flags in - <code>SCREEN</code></li> - </ul> + <li> + <p>added configure check for Win32 named pipes feature, using + that to make <tt>nc_mingw.h</tt> obsolete in favor of + <tt>nc_win32.h</tt></p> + </li> + + <li>separated the <tt>_NC_WINDOWS</tt> platform macro into + <tt>_NC_WINDOWS_NATIVE</tt>, for MinGW and other native Win32 + support, and <tt>_NC_WINDOWS</tt>, to make some Win32 features + available under the Cygwin runtime, in this case the + term-driver.</li> + + <li> + <p>modified MinGW32 configuration to account for its use of + Windows-style pathnames in filesystem checks.</p> + </li> - <p>This release drops compatibility with obsolete versions of - <a href="https://invisible-island.net/ncurses/tack/">tack</a>, e.g., pre-1.08</p> + <li> + <p>changed <tt>MS_TERMINAL</tt> symbol to + <tt>DEFAULT_TERM_VAR</tt></p> + </li> + + <li> + <p>updated <tt>ncurses/wcwidth.c</tt>, for MinGW ports, from + xterm.</p> + </li> + + <li> + <p>made fixes for reading Unicode characters in MinGW/Windows + port</p> + </li> + + <li> + <p>improved Windows driver by restoring the scroll buffer and + console mode, e.g., when <tt>reset_prog_mode</tt> or + <tt>endwin</tt> is called</p> + </li> + + <li> + <p>simplified include for <tt>wchar.h</tt> in Windows port by + removing the platform ifdef's</p> + </li> + + <li> + <p>modified driver for MinGW to handle shift-tab and + control-tab as back-tab</p> + </li> + + <li> + <p>made fixes for port using clang-cl or cl MSVC</p> + </li> + </ul> <h4><a name="h4-fixes-library" id="h4-fixes-library">Other improvements</a></h4> @@ -242,108 +297,145 @@ <ul> <li> - <p>In addition to the new, safer function - <code>tiparm_s</code>, ncurses adds checks to make the older - <code>tiparm</code>, <code>tparm</code> and - <code>tgoto</code> functions safer:</p> + <p>add comments to generated <tt>term.h</tt> to hint the + configure options used</p> + </li> - <ul> - <li> - <p>the terminfo functions <code>tiparm</code> and - <code>tparm</code> ensure that the capability string - comes from the terminal description which ncurses loads, - rather than from random data which the application - happens to have.</p> - </li> + <li> + <p>change scope of <tt>TTY</tt>, <tt>GET_TTY</tt> and + <tt>SET_TTY</tt> to ncurses-internals</p> + </li> + <li> + <p>improved mouse driver</p> + + <ul> <li> - <p>the <code>tgoto</code> function disallows capabilities - which its analysis shows will attempt to use string - parameters.</p> + <p>modify <tt>handle_wheel</tt> case 2 to ignore the + event as in case 1 for mouse version 1, since that + corresponds to a button 6 or 7 event which is not + supported with ABI 6.</p> </li> <li> - <p>ncurses uses internal functions which correspond to - <code>tiparm</code>, and <code>tgoto</code> which ensure - that the capability strings which are passed to these - functions come from the loaded terminal description.</p> + <p>use separate read/write pointers in the mouse event + queue to work with too-close events for the + click-detection to work reliably, and further improve + that in case <tt>mouseinterval(0)</tt> is used to + suppress click-detection.</p> </li> </ul> </li> <li> - <p>improve check in <code>lib_tparm.c</code>, ensuring that a - char* fits into a <code>TPARM_ARG</code></p> + <p>modify treatment of <em>“n”</em> parameter for + <tt>waddnstr</tt>, <tt>waddnwstr</tt>, and + <tt>wins_nwstr</tt> to return <em>OK</em> when + <em>“n”</em> is zero, for consistency with other + implementations</p> + </li> + + <li> + <p>modify <tt>wattron</tt>/<tt>wattroff</tt> calls in + <tt>form/m_post.c</tt> to call <tt>wattr_on</tt> and + <tt>wattr_off</tt> to omit cast used in the former for X/Open + compatibility</p> + </li> + + <li> + <p>change <tt>winwstr</tt> to a generated function, using the + macro definition, moving its handling of negative length + parameter into <tt>winnwstr</tt>.</p> + </li> + + <li> + <p>change <tt>winwstr</tt> to return wide character count + instead of <em>OK</em>.</p> + </li> + + <li> + <p>disallow directories and block/character devices in + safe-open.</p> + </li> + + <li> + <p>amend <tt>scr_restore</tt> and <tt>scr_init</tt> to remove + the target window only after validating the source window + which will replace the target</p> </li> <li> - <p>modify <code>_nc_syserr_abort</code> to use - <code>_nc_env_access</code>, rather than only checking root - uid</p> + <p>modify <tt>_nc_flush</tt> to also flush <em>stderr</em> to + help the <em>flash</em> capability to work in + <tt>bash</tt></p> </li> <li> - <p>improve thread lock in <code>lib_trace.c</code></p> + <p>trim padding from <em>sgr</em> expression used in + <tt>trim_sgr0</tt>, to avoid copying the padding into the + resulting sgr0</p> </li> <li> - <p>modify <code>flushinp</code> to use file descriptors in - <code>SCREEN</code>, rather than from <code>TERMINAL</code>, - and check if they are for a terminal, like SVr4</p> + <p>modify <tt>misc/Makefile.in</tt> and + <tt>misc/run_tic.in</tt> so that <tt>$DESTDIR</tt> is set and + used only in the makefile.</p> </li> <li> - <p>modify <code>mcprint</code> to use file descriptor in - <code>SCREEN</code>, for consistency</p> + <p>modify <tt>MKfallback.sh</tt> to eliminate + <tt>TERMINFO</tt> environment variable.</p> </li> <li> - <p>modify internal function <code>_nc_read_file_entry</code> - to show relevant filename in warnings</p> + <p>add <tt>-x</tt> option to <tt>infocmp</tt> in + <tt>MKfallback.sh</tt></p> </li> <li> - <p>improve checks in internal function - <code>convert_string</code> for corrupt terminfo entry</p> + <p>limit value from <tt>ESCDELAY</tt> environment variable to + 30 seconds, like other delay limits.</p> </li> <li> - <p>review/improve handling of out-of-memory conditions</p> + <p>limit values from <tt>LINES</tt> and <tt>COLUMNS</tt> + environment variables to 512</p> </li> <li> - <p>limit delays to 30 seconds, i.e., padding delays in - terminfo, as well as <code>napms</code> and - <code>delay_output</code> functions</p> + <p>added check in <tt>wresize</tt> for out-of-range + dimensions</p> </li> <li> - <p>fix reallocation loop for <code>vsnprintf</code> in - <code>_nc_sprintf_string</code> by copying the va_list - variable</p> + <p>improved error-handling in c++ binding</p> </li> <li> - <p>modify <code>delscreen</code> to limit the windows which - it creates to just those associated with the screen</p> + <p>improved error-reporting in <tt>write_entry.c</tt></p> </li> <li> - <p>modify <code>endwin</code> to return an error if it is - called again without an intervening screen update</p> + <p>amended limit used in <tt>alloc_pair</tt>, by applying an + adjustment for default colors only when the maximum number of + color pairs is greater than the maximum number of colors</p> </li> <li> - <p>modify <code>wenclose</code> to handle pads</p> + <p>added limit-checks in <tt>alloc_entry.c</tt> and + <tt>alloc_ttype.c</tt> to avoid indexing errors when using + <tt>infocmp</tt> to compare all capabilities when processing + a malformed terminfo binary which has a valid header</p> </li> <li> - <p>eliminate use of <code>PATH_MAX</code> in - <code>lib_trace.c</code></p> + <p>added a null pointer check in mouse-initialization, for + the Windows driver</p> </li> <li> - <p>provide for any <code>CCHARW_MAX</code> greater than 1</p> + <p>added some null-pointer checks after <tt>malloc</tt>s in + test-programs.</p> </li> </ul> @@ -351,42 +443,41 @@ <ul> <li> - <p>correct loop termination condition in - <code>waddnstr</code> and <code>waddnwstr</code></p> + <p>removed test in <tt>wgetch</tt> which applied + <tt>notimeout</tt> to the initial read of a character</p> </li> <li> - <p>improve parsing in internal function - <code>_nc_msec_cost</code>, allowing a single decimal - point</p> + <p>added check for special case of <tt>wcrtomb</tt> + converting a single byte code to a different single byte + code, which glibc does for code 160 in the KOI8-R + encoding</p> </li> <li> - <p>amend parameter check for entire string versus specific - length in <code>winsnstr</code> and <code>wins_nwstr</code> - to match Solaris; make similar correction to - <code>wins_nwstr</code></p> + <p>corrected <tt>_nc_to_char</tt> for the case when + <tt>wctob</tt> is not found by configure script</p> </li> <li> - <p>correct internal function <code>wadd_wch_literal</code> - when adding a non-spacing character to a double-width + <p>revised loop in <tt>wins_nwstr</tt>, to ensure that + non-spacing characters are combined with the base spacing character</p> </li> <li> - <p>correct definition of <code>Charable</code> macro for - non-wide ncurses library .</p> + <p>modified checks in <tt>delwin</tt> to avoid checking if + the window is a pad until first checking if it is still on + the active window-list</p> </li> </ul> <h3><a name="h3-programs" id="h3-programs">Program improvements</a></h3> - <p id="h4-utilities">Several improvements were made to the - utility programs. Some were done to make the <code>infocmp</code> - option “<tt>-u</tt>” option help refactor the - terminal database.</p> +<h4><a name="h4-utilities">Utilities</a></h4> + <p>Several improvements were made to the + utility programs.</p> <dl> <dt><span class="part-name"><a href= @@ -396,26 +487,32 @@ <dd> <ul> <li> - <p>add limit checks for processing extended capabilities - with the “<code>-u</code>” option</p> + <p>improved <tt>infocmp</tt> <tt>-E</tt>/<tt>-e</tt> + fallback feature</p> + + <ul> + <li>prefix names with “<tt>ti_</tt>” if + they begin with a digit, e.g., 9term</li> + + <li>escape backslashes and double-quotes in description + fields</li> + </ul> </li> <li> - <p>correct initial alignment of extended capabilities, so - that the “<code>-u</code>” option can be used - for more than two terminal types</p> + <p>modified <tt>infocmp</tt> <tt>-E</tt>/<tt>-e</tt> + fallback feature to reduce stricter compiler warnings for + the extended capability data.</p> </li> <li> - <p>modify “<code>-u</code>” option to not - report cancels for strings which were already cancelled - in a use'd chunk.</p> + <p>modified <tt>infocmp</tt> and <tt>tabs</tt> to use + actual name in usage and header.</p> </li> <li> - <p>correct an assignment “<code>-u</code>” - for detecting if a boolean is unset in a base entry and - set in a use'd chunk, i.e., if it was cancelled.</p> + <p>improved error-message from <tt>infocmp</tt> when a + terminal entry cannot be opened</p> </li> </ul> </dd> @@ -427,50 +524,32 @@ <dd> <ul> <li> - <p>correct limit-check when dumping tc/use clause via - “<code>-I</code>”</p> + <p>increased limit on use-clauses from 32 to 40, warn but + allow entries which exceed the old limit.</p> </li> <li> - <p>check return value of <code>_nc_save_str</code>, in - special case where extended capabilities are processed - but the terminal description was not initialized</p> + <p>added check for infinite loop in <tt>tic</tt>'s + use-resolution.</p> </li> <li> - <p>modify check for multiply defined aliases to report - problems within the current runtime rather than for - conflicts with pre-existing terminal descriptions.</p> - </li> - - <li> - <p>disallow using <code>$TERMINFO</code> or - <code>$HOME/.terminfo</code> when - “<code>-o</code>” option is used</p> + <p>added a buffer-limit check in + <tt>postprocess_termcap</tt></p> </li> </ul> </dd> <dt><span class="part-name"><a href= - "https://invisible-island.net/ncurses/man/tput.1.html">tput</a></span> and <span class= - "part-name"><a href= - "https://invisible-island.net/ncurses/man/tset.1.html">tset</a></span></dt> + "https://invisible-island.net/ncurses/man/tput.1m.html">tput</a></span> + </dt> <dd> <ul> <li> - <p>add “<code>-v</code>” option to tput, to - show warnings</p> - </li> - - <li> - <p>modify <em>reset</em> command to avoid altering clocal - if the terminal uses a modem</p> - </li> - - <li> - <p>modify <em>reset</em> feature to avoid 1-second sleep - if running in a pseudo-terminal</p> + <p>Warn about capabilities which expect parameters where + none are given. Also, repair the feature where multiple + capabilities can be handled on a single line.</p> </li> </ul> </dd> @@ -484,41 +563,53 @@ <ul> <li> - <p>modify <code>test_tparm</code> to account for extended - capabilities</p> + <p>add help-popup for <tt>test_instr.c</tt>, + <tt>test_inwstr.c</tt></p> + </li> + + <li> + <p>add options to <tt>test/worm.c</tt> for benchmarking.</p> </li> <li> - <p>corrected mouse mask in <code>test/testcurs.c</code></p> + <p>improve <tt>-t</tt> option of <tt>test/gdc.c</tt>, + allowing hours only, or hours and minutes only.</p> </li> <li> - <p>modify <code>test/clip_printw.c</code> to optionally test - non-wrapped updates</p> + <p>correct dimensions in <tt>test/popup_msg.c</tt>, fixing an + overrun.</p> </li> <li> - <p>modify <code>test/test_mouse.c</code> to use curses api - for raw/noraw</p> + <p>modify <tt>test/demo_keyok.c</tt> to accept <tt>^Q</tt> + for quit, for consistency.</p> </li> <li> - <p>modify <code>test/clip_printw.c</code> to optionally test - non-wrapped updates</p> + <p>add option “<tt>-c</tt>” to test programs to + illustrate a non-blank character in the window background + property.</p> + </li> + + <li> + <p>reserve <tt>-c</tt>/<tt>-l</tt> options in + <tt>test/*.c</tt> for command/logging like <a href= + "https://invisible-island.net/vttest/">vttest</a>.</p> </li> </ul> - <p>There is one new demo/test programs:</p> + <p>There is one new demo/test program:</p> <dl> - <dt><span class="part-name"><em>test/test_endwin.c</em></span> + <dt><span class= + "part-name"><em>ncurses/report_ctype.c</em></span> </dt> <dd> - <p>This program shows the return-status from - <code>endwin</code> with different combinations of - <code>endwin</code> (repeated), <code>initscr</code>, - <code>newterm</code>.</p> + <p>Shows a chart of the first 256 character codes, which are + not as consistent across platforms for ctype versus wctype as + some suppose.</p> </dd> </dl> @@ -529,61 +620,82 @@ <ul> <li> <p><a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-ansi_apparrows"><tt>ansi+apparrows</tt></a></p> + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ghostty"><tt>ghostty</tt></a></p> </li> <li> <p><a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-contour"><tt>contour</tt></a></p> + "https://invisible-island.net/ncurses/terminfo.src.html#tic-illumos"><tt>illumos</tt></a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-sun-16color"><tt>sun-16color</tt></a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-sun-256color"><tt>sun-256color</tt></a>, + and <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-sun-direct"><tt>sun-direct</tt></a></p> </li> <li> <p><a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-linux_kbs"><tt>linux+kbs</tt></a> - for terminals which imitate xterm's behavior with Linux</p> + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ms-terminal-direct"><tt>ms-terminal-direct</tt></a></p> </li> <li> <p><a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-rio"><tt>rio</tt></a>, - <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-rio-direct"><tt>rio-direct</tt></a></p> + "https://invisible-island.net/ncurses/terminfo.src.html#tic-pangoterm"><tt>pangoterm</tt></a></p> </li> <li> <p><a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-mostlike"><tt>mostlike</tt></a></p> + "https://invisible-island.net/ncurses/terminfo.src.html#tic-rlogin-color"><tt>rlogin-color</tt></a></p> </li> <li> <p><a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-ms-vt100-16color"><tt>ms-vt100-16color</tt></a>, - <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-winconsole"><tt>winconsole</tt></a></p> + "https://invisible-island.net/ncurses/terminfo.src.html#tic-sclp"><tt>sclp</tt></a></p> </li> <li> <p><a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt100_noapp"><tt>vt100+noapp</tt></a>, + "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt520-w"><tt>vt520-w</tt></a> + and <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt525-w"><tt>vt525-w</tt></a></p> + </li> + </ul> + + <p>along with building blocks</p> + + <ul> + <li> + <p><a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-linux_lockeys"><tt>linux+lockeys</tt></a>, <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt100_noapp_pc"><tt>vt100+noapp+pc</tt></a>, + "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_r5_lockeys"><tt>xterm+r5+lockeys</tt></a>, <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_app_pc"><tt>xterm+app+pc</tt></a>, + "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_r5_fkeys"><tt>xterm+r5+fkeys</tt></a></p> + </li> + + <li> + <p><a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt100_pf1-pf4"><tt>vt100+pf1-pf4</tt></a></p> + </li> + + <li> + <p><a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_ufkeys"><tt>vt220+ufkeys</tt></a>, <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_decedit"><tt>xterm+decedit</tt></a> - from <a href="https://invisible-island.net/xterm/xterm.log.html#xterm_389">xterm - #389</a></p> + "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_sfkeys"><tt>vt220+sfkeys</tt></a></p> </li> <li> <p><a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-putty_cursor"><tt>putty+cursor</tt></a> - to reflect amending of modified cursor-keys in 2021</p> + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ecma_standout"><tt>ecma+standout</tt></a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ecma_underline"><tt>ecma+underline</tt></a></p> </li> <li> <p><a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-wezterm"><tt>wezterm</tt></a></p> + "https://invisible-island.net/ncurses/terminfo.src.html#tic-wyse+cvis"><tt>wyse+cvis</tt></a></p> </li> </ul> @@ -598,88 +710,149 @@ <ul> <li> - <p><a href= - "https://invisible-island.net/ncurses/terminfo.src.html#toc-_X_T_E_R_M__Extensions_">document</a> - XF, kxIN and kxOUT</p> + <p>use <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_keypad">xterm+keypad</a> + in <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-pccon_base">pccon+base</a></p> </li> <li> - <p>add note on <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-sun"><tt>sun</tt></a> - regarding wscons/cmdtool/shelltool</p> + <p>use <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-bracketed_paste">bracketed+paste</a> + in <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-nsterm">nsterm</a>, + <a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-rlogin-color">rlogin-color</a>, + <a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-screen">screen</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-terminology">terminology</a></p> </li> <li> - <p>remove DECCOLM+DECSCLM from <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-foot"><tt>foot</tt></a></p> + <p>use extended-keys in <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-djgpp">djgpp</a> 2.05</p> </li> <li> - <p>add xterm+focus to <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-foot_base"><tt>foot+base</tt></a></p> - </li> + <p>update/correct some of the rv/xr strings, checked with</p> - <li> - <p>add ecma+strikeout to <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-putty"><tt>putty</tt></a></p> - </li> + <p><a href="https://invisible-island.net/ncurses/tack.html">tack</a></p> - <li> - <p>use CSI 3J in <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-vte-2017"><tt>vte-2017</tt></a></p> + <ul> + <li>add rv code for <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-alacritty">alacritty</a></li> + + <li>add xr code for <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-putty">putty</a></li> + + <li>add rv/xr codes for <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-domterm">domterm</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-mintty">mintty</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-mlterm">mlterm</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-contour">contour</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ghostty">ghostty</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-iterm2">iterm2</a>, + <a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-kitty">kitty</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-konsole">konsole</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-vscode">vscode</a>, + <a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-vte">vte</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-wezterm">wezterm</a></li> + </ul> </li> <li> - <p>use oldxterm+sm+1006 in <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-vte-2014"><tt>vte-2014</tt></a></p> + <p>improve use-clauses: <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ansi_cup">ansi+cup</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ansi_idl1">ansi+idl1</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ansi_rca">ansi+rca</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ansi_rca2">ansi+rca2</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ansi_sgrso">ansi+sgrso</a>, + <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ansi_sgrul">ansi+sgrul</a></p> </li> <li> - <p>modify <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-xgterm"><tt>xgterm</tt></a> - to work around line-drawing bug</p> + <p><a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-sclp">sclp</a>:</p> + + <ul> + <li>add kf1 to kf5</li> + + <li>use <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ansi_rca">ansi+rca</a></li> + + <li>use <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-vt220_pcedit">vt220+pcedit</a></li> + </ul> </li> <li> - <p>add xterm focus mode 1004 to <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_focus"><tt>xterm+focus</tt></a> - as fe/fd capabilities, like vim.</p> + <p><a href="https://invisible-island.net/ncurses/terminfo.src.html#tic-vt525">vt525</a></p> + + <ul> + <li>add color</li> + + <li>add op</li> + </ul> </li> <li> - <p>add xterm+focus to <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-alacritty_common"><tt>alacritty+common</tt></a></p> + <p><a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-wezterm">wezterm</a>:</p> + + <ul> + <li>use <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_alt_title">xterm+alt+title</a></li> + + <li>omit its broken left/right margin feature</li> + </ul> </li> + <li>update <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-contour">contour</a></li> + <li> - <p>add XR/xr, to work with vim, and use RV/rv to denote DA2 - and its response</p> + <p>update <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-ms-terminal">ms-terminal</a></p> + + <ul> + <li>add XM/xm to ms-terminal, to enable mouse with + experimental Windows driver</li> + </ul> </li> <li> - <p>add XF flag to <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm_focus"><tt>xterm+focus</tt></a> - so that termcap applications can be aware of terminals which - may support focus in/out</p> + <p>update <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-st">st</a> to 0.8.5</p> </li> <li> - <p>use xterm+focus in <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-xterm-p370"><tt>xterm-p370</tt></a> - and <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-tmux"><tt>tmux</tt></a></p> + <p>update <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-teraterm">teraterm</a> to + 5.0</p> </li> <li> - <p>remove xterm+sm+1006 from <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-tmux"><tt>tmux</tt></a></p> + <p>update <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-foot">foot</a> to + 1.18.1</p> </li> <li> - <p>NetBSD-related fixes for <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-x68k"><tt>x68k</tt></a> and - <a href= - "https://invisible-island.net/ncurses/terminfo.src.html#tic-wsvt25"><tt>wsvt25</tt></a></p> + <p>update <a href= + "https://invisible-island.net/ncurses/terminfo.src.html#tic-iterm2">iTerm2</a> to + 3.5.0</p> </li> </ul> @@ -715,67 +888,12 @@ <ul> <li> - <p>add assignment in <code>CF_MAN_PAGES</code> to fill in - value for <code>TERMINFO_DIRS</code> in ncurses, terminfo - and tic manpages.</p> + <p>corrected note about box() in curs_border.3x</p> </li> <li> - <p>clarify interaction of <code>-R</code> option versus - <code>-C</code>, <code>-I</code> and <code>-r</code> in - <code>infocmp</code> manpage.</p> - </li> - - <li> - <p>correct manpage description of panel_hidden.</p> - </li> - - <li> - <p>improve manpage description for addch versus unctrl - format used for non-printable characters.</p> - </li> - - <li> - <p>improve manpages discussing file descriptors in - low-level functions.</p> - </li> - - <li> - <p>improve description of search rules for terminal - descriptions in terminfo manpage.</p> - </li> - - <li> - <p>modify dist.mk to avoid passing developer's comments - in manpages into the generated html documentation.</p> - </li> - - <li> - <p>modify test-package "ncurses6-doc" to use - manpage-aliases, which in turn required a change to the - configure script to factor in the extra-suffix option - when deriving alias names.</p> - </li> - </ul> - </li> - - <li> - <p>New/improved history and portability sections:</p> - - <ul> - <li> - <p>add information about "ttycap", termcap's forerunner, - to tset.1</p> - </li> - - <li> - <p>document limitations of tparm, and error-returns in - curs_terminfo.3x</p> - </li> - - <li> - <p>document limitations of tgoto, and error-returns in - curs_termcap.3x</p> + <p>added note on scrolling and lower-right corner to + waddch and wadd_wch manual pages.</p> </li> </ul> </li> @@ -786,17 +904,17 @@ <ul> <li> <p>This release has many changes to improve the - formatting and style of the manpages.</p> + formatting and style of the man pages.</p> </li> <li> - <p>Manpages now use consistent section-naming, page - headers and footers (including the modification date for - each page).</p> + <p>Table layout in the man pages has been revised.</p> </li> <li> - <p>Table layout has been revised.</p> + <p>The <a href= + "https://invisible-island.net/ncurses/howto/NCURSES-Programming-HOWTO.html">ncurses + HOWTO</a> and its sample programs has been updated.</p> </li> </ul> </li> @@ -808,82 +926,66 @@ <h3><a name="h3-bug-fixes" id="h3-bug-fixes">Interesting bug-fixes</a></h3> - <p>The changes to <tt>tparm</tt>, <tt>tgoto</tt> which improve - the design of the low-level interfaces are <em>interesting</em>, - but are not bug-fixes <em>per se</em>.</p> - <h3><a name="h3-config-config" id= "h3-config-config">Configuration changes</a></h3> <h4><a name="h4-config-major" id="h4-config-major">Major changes</a></h4> - <p>These are the major changes (aside from introducing <a href= - "#h4-new-library"><tt>tiparm_s</tt></a>):</p> + <p>Improvements made to configure checks include</p> <ul> <li> - <p>use wide-character (ncursesw) by default</p> + <p>improve configure check for “install”.</p> </li> <li> - <p>use opaque typedefs by default</p> + <p>add check for build-time utilities, in case + cross-compiling is setup with an invalid + <tt>$BUILD_CC</tt></p> </li> - </ul> - <p>However, most of the work on configure scripts was done to - reduce warnings within the configure script:</p> - - <ul> <li> - <p>intrusive warnings from GNU grep regarding fgrep and - egrep</p> + <p>add configure check for <tt><sys/fsuid.h></tt>, + which may be needed for flatpacks</p> </li> <li> - <p>fatal errors in compile-checks, arising from recent - “Modern C” efforts by some developers which - caused longstanding configure checks to fail.</p> - - <p>After repairing the configure script, none of that - activity affected ncurses because stricter warnings are used - routinely in development.</p> + <p>add a consistency-check for termio(s)/tty headers, to help + with cross-compiles</p> </li> - </ul> - <p>Other improvements made to configure checks include</p> - - <ul> <li> - <p>use <a href= - "https://invisible-island.net/ncurses/INSTALL.html#option:enable-string-hacks">string-hacks</a> - in alloc_entry.c, alloc_type.c and hardscroll.c, overlooked - due to compiler changes in recent OpenBSD releases</p> + <p>modify configure check for + <tt>MAKEFLAGS</tt>/<tt>MFLAGS</tt> to ignore existing value + of these environment variables</p> </li> <li> - <p>revise progs.priv.h to provide for NC_ISATTY reuse</p> + <p>improve configurability of <tt>alloca</tt> as used in + Windows ports.</p> </li> <li> - <p>configure check for MB_LEN_MAX provides warning as - needed</p> + <p>modify configure script checks for <tt>stdbool.h</tt> to + fix build with older gcc version.</p> </li> <li> - <p>trim a space after some "-R" options, fixing builds for - applications built using clang and ncurses on Solaris</p> + <p>add <new> to the possible headers declaring the C++ + <tt>std::bad_alloc</tt>.</p> </li> <li> - <p>work around misconfiguration of MacPorts gcc13, which - exposes invalid definition of <tt>MB_LEN_MAX</tt> in gcc's - fallback copy of <tt>limits.h</tt></p> + <p>modify check for <tt>stdbool.h</tt> to be more + conservative in case the headers are used with a compiler + other than that which was used to configure</p> </li> <li> - <p>modified experimental Windows driver works with xterm - mouse protocol</p> + <p>remove dependency on <tt>stdbool.h</tt> from configure + script check for type of <em>bool</em> when C++ binding is + omitted.</p> </li> </ul> @@ -894,50 +996,26 @@ <dl> <dt><a href= - "https://invisible-island.net/ncurses/INSTALL.html#option:disable-setuid-environ"><tt>--disable-setuid-environ</tt></a> - </dt> - - <dd> - <p>Compile with environment restriction, so certain - environment variables are not available when running via a - setuid/setgid application. These are (for example - <tt>$TERMINFO</tt>) those that allow the search path for the - terminfo or termcap entry to be customized.</p> - - <p>A setuid/setgid application inherits its environment - variables from the current user, in contrast to sudo which - may limit the environment variables that ncurses uses.</p> - </dd> - - <dt><a href= - "https://invisible-island.net/ncurses/INSTALL.html#option:enable-check-size"><tt>--enable-check-size</tt></a> - </dt> - - <dd> - <p>Compile-in feature to detect screensize for terminals - which do not advertise their screensize, e.g., serial - terminals.</p> - </dd> - - <dt><a href= - "https://invisible-island.net/ncurses/INSTALL.html#option:with-abi-altered"><tt>--with-abi-altered=<em>NUM</em></tt></a> + "https://invisible-island.net/ncurses/INSTALL.html#option:enable-install-prefix"><tt>--enable-install-prefix</tt></a> </dt> <dd> - <p>Override the displayed (rather than compiled-in) ABI. Only - packagers who have created configurations where the ABI - differs from ncurses should be interested in this option.</p> + <p>Modify behavior of <tt>$DESTDIR</tt> to merge or replace + the value set by <tt>--prefix</tt>.</p> </dd> <dt><a href= - "https://invisible-island.net/ncurses/INSTALL.html#option:with-strip-program"><tt>--with-strip-program=<em>XXX</em></tt></a> + "https://invisible-island.net/ncurses/INSTALL.html#option:enable-named-pipes"><tt>--enable-named-pipes</tt></a> </dt> <dd> - <p>When stripping executables during install, use the - specified program rather than “strip” overriding - program chosen by the install program for stripping - executables.</p> + <p>The Windows driver uses named pipes for communicating with + a pseudo console, allowing it to use escape sequences rather + than Console API. This works well with mintty. On the + downside, this feature may not work well with the Windows + Terminal due to a longstanding bug in <tt>conhost.exe</tt> + (<a href= + "https://github.com/microsoft/terminal/issues/9461">#9461</a>).</p> </dd> </dl> @@ -945,146 +1023,186 @@ <dl> <dt><a href= - "https://invisible-island.net/ncurses/INSTALL.html#option:with-pkg-config-libdir"><tt>--with-pkg-config-libdir[=<em>DIR</em>]</tt></a> + "https://invisible-island.net/ncurses/INSTALL.html#option:enable-exp-win32"><tt>--enable-exp-win32</tt></a> </dt> <dd> - <p>The optional <em>DIR</em> parameter can now be - “auto” to automatically use pkg-config's library - directory.</p> - - <p>The default is <tt>$(libdir)</tt>.</p> + <p>This option is obsolete, replaced by + <tt>--enable-named-pipes</tt>.</p> </dd> <dt><a href= - "https://invisible-island.net/ncurses/INSTALL.html#option:with-xterm-kbs"><tt>--with-xterm-kbs[=<em>XXX</em>]</tt></a> + "https://invisible-island.net/ncurses/INSTALL.html#option:enable-term-driver"><tt>--enable-term-driver</tt></a> </dt> <dd> - <p>The default is “auto” which tells the - configure script to choose BS or DEL according to platform - defaults.</p> + <p>This is enabled by default on platforms where the Windows + driver can be compiled, e.g., Cygwin, MinGW32 and MSYS2.</p> </dd> </dl> - <h3><a name="h3-portability" id="h3-portability">Portability</a></h3> + <h4><a name="h4-config-package" id="h4-config-package">Package + configuration scripts</a></h4> - <p>Many of the portability changes are implemented via the - configure script:</p> + <p>The configure script and makefiles optionally generate a + script which reports the compiler and linker options needed to + build a program with ncurses, as well as a data file which is + used via pkg-config for the same purpose. Several improvements + were made for these scripts:</p> <ul> <li> - <p>add/use configure check for <code>clock_gettime</code>, to - supersede <code>gettimeofday</code>.</p> + <p>improved filtering of <tt>-L</tt> options in + <tt>misc/gen-pkgconfig.in</tt> and in + <tt>misc/ncurses-config.in</tt></p> </li> <li> - <p>modify configure script check for pkg-config library - directory to take into account an older version 0.15.0 which - used PKG_CONFIG_PATH but not PKG_CONFIG_LIBDIR</p> + <p>modified <tt>ncurses*-config</tt> to add <tt>-I</tt> + option in <tt>--cflag</tt> where needed for + <tt>--disable-overwrite</tt> to match ".pc" files.</p> </li> <li> - <p>allow for MinGW32-/64-bit configurations to use - _DEFAULT_SOURCE</p> + <p>suppressed <tt>-g</tt> and <tt>-fXXX</tt> flags from + <tt>CFLAGS</tt> in <tt>misc/ncurses-config.in</tt></p> </li> <li> - <p>modify CF_XOPEN_SOURCE macro's amend default case to avoid - undefining _XOPEN_SOURCE if _POSIX_C_SOURCE is defined</p> + <p>modified configure script to allow for <tt>pkg-config</tt> + using DOS/Windows pathname syntax</p> </li> <li> - <p>updated configure script macro CF_XOPEN_SOURCE, for - uClibc-ng</p> + <p>modified <tt>misc/ncurses-config.in</tt>, improved match + with <tt>pkg-config output</tt>.</p> </li> <li> - <p>modify version-check for gcc/g++, now works for msys2</p> + <p>adjusted naming of test packages for MinGW + <tt>*-config</tt> scripts to match the <tt>pkg-config</tt> + names</p> </li> <li> - <p>build-fixes related to configure-options and/or - platform:</p> - - <ul> - <li>fix for <tt>--enable-fvisibility</tt></li> - - <li>fix for unusual values of - <tt>--with-rel-version</tt></li> + <p>added <tt>--cflags-only-I</tt> and + <tt>--cflags-only-other</tt> options to + <tt>misc/ncurses-config.in</tt></p> + </li> + </ul> - <li>fix for unusual values of - <tt>--with-abi-version</tt></li> + <h3><a name="h3-portability" id="h3-portability">Portability</a></h3> - <li>fix for <tt>--disable-tcap-names</tt></li> + <p>Many of the portability changes are implemented via the + configure script:</p> - <li>fix for termcap in <tt>nc_access.h</tt></li> - </ul> + <ul> + <li> + <p>disallow configure options which apply only to multiuser + systems, to improve ports to single-user systems such as + Haiku</p> </li> <li> - <p>other configure-script improvements:</p> + <p>add warning to configure script to address conflict + between the <tt>--enable-lp64</tt> option and the options for + overriding the types used for <tt>chtype</tt> and + <tt>mmask_t</tt>.</p> + </li> - <ul> - <li>recent msys2 headers work with - <tt>_DEFAULT_SOURCE</tt>; amend check</li> + <li> + <p>modify configure script cases for $host_os, to accommodate + 64-bit big-endian POWER Linux with glibc</p> + </li> - <li>use <tt>$ac_includes_default</tt> in most cases where - stdlib.h should work</li> + <li> + <p>modify configure script and misc/Makefile to accept glob + expressions that include Windows/DOS drive-letters</p> + </li> - <li>use <tt>#error</tt> consistently vs "make an - error"</li> + <li> + <p>change <tt>Ada95/configure</tt> to use + <tt>--with-screen</tt> option rather than + <tt>--enable-widec</tt>, to provide more choices of + underlying curses library.</p> + </li> - <li>add configure macro for <tt>gettimeofday</tt> vs inline - check</li> - </ul> + <li> + <p>modify configure script to work around broken gnatgcc + script found in gcc-13 builds.</p> </li> </ul> - <p>Here are some of the other portability fixes:</p> + <p>Other portability fixes include:</p> <ul> <li> - <p>modify configure scripts/makefiles to omit - <tt>KEY_RESIZE</tt> if the corresponding <tt>SIGWINCH</tt> - feature is disabled</p> + <p>improve pattern used for configure + <tt>--with-xterm-kbs</tt> option.</p> + </li> + + <li> + <p>modify recursive make rules to avoid interference with GNU + make's "-j" option</p> + </li> + + <li> + <p>when installing the terminfo database, check if symbolic + links are supported before attemping to link lib/terminfo + from share/terminfo</p> + </li> + + <li> + <p>improve logic in misc/run_tic.in for constructing symbolic + link when <tt>$DESTDIR</tt> is set.</p> + </li> + + <li> + <p>build-fix for ncurses-examples with newer PDCurses, which + no longer has stubs for unimplemented features.</p> + </li> + + <li> + <p>change <tt>etip.h.in</tt> to include either/both of + <tt><new></tt> and <tt><exception></tt>, needed + for another old BSD.</p> </li> <li> - <p>increase <tt>MB_CUR_MAX</tt> to 16, matching glibc's - <tt>MB_LEN_MAX</tt></p> + <p>correct conditional-compile for a case when the C compiler + does not have a bool type.</p> </li> <li> - <p>add BSD <tt>erase2</tt> to characters handled by - tset/reset</p> + <p>improve <tt>MKlib_gen.sh</tt> handling of + “bool” type, for building link_test.</p> </li> <li> - <p>use <tt>getauxval</tt> when available, to improve - <tt>setuid</tt>/<tt>setgid</tt> checks</p> + <p>modify <tt>ncurses/tinfo/MKfallback.sh</tt> to work with + MacOS <tt>sed</tt>, which lacks BSD-style <tt>\<</tt> and + <tt>\></tt>.</p> </li> <li> - <p>set <tt>dwShareMode</tt> in calls to - <tt>CreateConsoleScreenBuffer</tt></p> + <p>modify <tt>MKlib_gen.c</tt> to allow for Solaris's + definition of <tt>NULL</tt> as <tt>0L</tt>.</p> </li> <li> - <p>use <tt>CreateFile</tt> with "<tt>CONIN$</tt>", - "<tt>CONOUT$</tt>" rather than <tt>GetStdHandle</tt> to - obtain a handle on the actual console, avoiding redirection - in the MinGW/Win32 configurations</p> + <p>widen pattern in pc/*-config scripts to disallow more + linker options.</p> </li> <li> - <p>modify MinGW driver to return <tt>KEY_BACKSPACE</tt> when - an unmodified <tt>VK_BACK</tt> virtual key is entered</p> + <p>avoid redefining bool in <tt>curses.h</tt> if the platform + already supports that type.</p> </li> <li> - <p>modify MinGW configuration to provide for running in - MSYS/MSYS2 shells, assuming ConPTY support</p> + <p>move include <tt><curses.h></tt> from + <tt>etip.h.in</tt> to <tt>cursesw.h</tt>, to work around + breakage in Apple's port of ncurses.</p> </li> </ul> @@ -1116,8 +1234,8 @@ <ul> <li> - <p>the panel library, supporting a stack of windows with - backing store</p> + <p>the panel library, permitting windows to stack and + overlap</p> </li> <li> @@ -1627,10 +1745,10 @@ <blockquote> <p><a href= - "https://invisible-island.net/archives/ncurses/6.4/">https://invisible-island.net/archives/ncurses/6.4/</a> + "https://invisible-island.net/archives/ncurses/6.5/">https://invisible-island.net/archives/ncurses/6.5/</a> and<br> <a href= - "https://invisible-mirror.net/archives/ncurses/6.4/">https://invisible-mirror.net/archives/ncurses/6.4/</a> .</p> + "https://invisible-mirror.net/archives/ncurses/6.5/">https://invisible-mirror.net/archives/ncurses/6.5/</a> .</p> </blockquote> <p>There is an archive of the mailing list here:</p> @@ -1701,7 +1819,7 @@ <li> <a href="#h3-library">Library improvements</a> <ul> - <li><a href="#h4-new-library">New features</a></li> + <li><a href="#h4-term-driver">Terminal driver</a></li> <li><a href="#h4-fixes-library">Other improvements</a></li> @@ -1730,6 +1848,8 @@ <li><a href="#h4-config-options">Configuration options</a></li> + <li><a href="#h4-config-package">Package + scripts</a></li> </ul> </li> diff --git a/doc/html/man/adacursesw6-config.1.html b/doc/html/man/adacursesw6-config.1.html index 3ded34ae5818..7a154812d5da 100644 --- a/doc/html/man/adacursesw6-config.1.html +++ b/doc/html/man/adacursesw6-config.1.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 2010-2014,2016 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: MKada_config.in,v 1.35 2024/04/20 21:13:27 tom Exp @ + * @Id: MKada_config.in,v 1.37 2025/04/05 22:26:08 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>adacursesw6\-config 1 2024-04-20 ncurses 6.5 User commands</TITLE> +<TITLE>adacursesw6\-config 1 2025-04-05 ncurses 6.6 User commands</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">adacursesw6\-config 1 2024-04-20 ncurses 6.5 User commands</H1> +<H1 class="no-header">adacursesw6\-config 1 2025-04-05 ncurses 6.6 User commands</H1> <PRE> <STRONG><A HREF="adacursesw6-config.1.html">adacursesw6-config(1)</A></STRONG> User commands <STRONG><A HREF="adacursesw6-config.1.html">adacursesw6-config(1)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>adacursesw6-config</STRONG> - configuration helper for <EM>AdaCurses</EM> libraries @@ -69,8 +67,8 @@ <STRONG>--libs</STRONG> reports the GNAT libraries needed to link with <EM>AdaCurses</EM>. - <STRONG>--version</STRONG> reports the release and patch date information of the - <EM>ncurses</EM> libraries used to configure and build <EM>AdaCurses</EM> and + <STRONG>--version</STRONG> reports the release and patch date information of the + <EM>ncurses</EM> libraries used to configure and build <EM>AdaCurses</EM> and exits successfully. <STRONG>--help</STRONG> issues a usage message and exits successfully. @@ -112,7 +110,6 @@ end loop; End_Windows; - end Hello; Then, using @@ -126,9 +123,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="adacursesw6-config.1.html">adacursesw6-config(1)</A></STRONG> +ncurses 6.6 2025-04-05 <STRONG><A HREF="adacursesw6-config.1.html">adacursesw6-config(1)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/captoinfo.1m.html b/doc/html/man/captoinfo.1m.html index 92f9905e2a88..1c9ddca8ca7d 100644 --- a/doc/html/man/captoinfo.1m.html +++ b/doc/html/man/captoinfo.1m.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2016 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: captoinfo.1m,v 1.63 2024/03/23 20:37:25 tom Exp @ + * @Id: captoinfo.1m,v 1.77 2025/11/12 01:03:56 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>captoinfo 1m 2024-03-23 ncurses 6.5 User commands</TITLE> +<TITLE>captoinfo 1m 2025-11-11 ncurses 6.6 User commands</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">captoinfo 1m 2024-03-23 ncurses 6.5 User commands</H1> +<H1 class="no-header">captoinfo 1m 2025-11-11 ncurses 6.6 User commands</H1> <PRE> <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG> User commands <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>captoinfo</STRONG> - convert a <EM>termcap</EM> description into a <EM>terminfo</EM> description @@ -63,10 +61,10 @@ equivalent <EM>terminfo</EM> description to the standard output stream. <EM>termcap</EM> <STRONG>tc</STRONG> capabilities translate to <EM>terminfo</EM> "<STRONG>use</STRONG>" capabilities. - If no <EM>file</EM>s are specified, <STRONG>captoinfo</STRONG> interprets the content of the - environment variable <EM>TERMCAP</EM> as a file name, and extracts only the - entry for the terminal named in the environment variable <EM>TERM</EM> from it. - If the environment variable <EM>TERMCAP</EM> is not set, <STRONG>captoinfo</STRONG> reads + If no <EM>file</EM>s are specified, <STRONG>captoinfo</STRONG> interprets the content of the + environment variable <EM>TERMCAP</EM> as a file name, and extracts only the + entry for the terminal type named in the environment variable <EM>TERM</EM> from + it. If the environment variable <EM>TERMCAP</EM> is not set, <STRONG>captoinfo</STRONG> reads <EM>/etc/termcap</EM>. This utility is implemented as a link to <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, with the latter's <STRONG>-I</STRONG> @@ -77,12 +75,11 @@ </PRE><H3><a name="h3-Translations-from-Nonstandard-Capabilities">Translations from Nonstandard Capabilities</a></H3><PRE> <STRONG>captoinfo</STRONG> translates some obsolete, nonstandard capabilities into - standard (SVr4/XSI Curses) <EM>terminfo</EM> capabilities. It issues a - diagnostic to the standard error stream for each, inviting the user to - check that it has not mistakenly translated an unknown or mistyped - capability name. + standard <EM>terminfo</EM> capabilities. It issues a diagnostic to the standard + error stream for each, inviting the user to check that it has not + mistakenly translated an unknown or mistyped capability name. - <STRONG>Name</STRONG> + <STRONG><EM>termcap</EM></STRONG> <STRONG>Code</STRONG> <STRONG>Obsolete</STRONG> <STRONG>Standard</STRONG> <STRONG>Origin</STRONG> <STRONG><EM>terminfo</EM></STRONG> <STRONG>capability</STRONG> --------------------------------------------------------- <STRONG>BO</STRONG> <STRONG>mr</STRONG> AT&T <STRONG>enter_reverse_mode</STRONG> @@ -111,14 +108,13 @@ <STRONG>KE</STRONG> <STRONG>F4</STRONG> Tektronix <STRONG>key_f14</STRONG> <STRONG>KF</STRONG> <STRONG>F5</STRONG> Tektronix <STRONG>key_f15</STRONG> <STRONG>BC</STRONG> <STRONG>Sb</STRONG> Tektronix <STRONG>set_background</STRONG> - <STRONG>FC</STRONG> <STRONG>Sf</STRONG> Tektronix <STRONG>set_foreground</STRONG> <STRONG>HS</STRONG> <STRONG>mh</STRONG> IRIX <STRONG>enter_dim_mode</STRONG> XENIX <EM>termcap</EM> had a set of extension capabilities, corresponding to box drawing characters of CCSID ("code page") 437, as follows. - <STRONG><EM>termcap</EM></STRONG> <STRONG>Name</STRONG> <STRONG>Graphic</STRONG> + <STRONG><EM>termcap</EM></STRONG> <STRONG>Code</STRONG> <STRONG>Graphic</STRONG> ----------------------------------------- <STRONG>G2</STRONG> upper left corner <STRONG>G3</STRONG> lower left corner @@ -144,27 +140,28 @@ <STRONG>Gc</STRONG> double intersection <STRONG>GG</STRONG> ACS magic cookie count - <STRONG>captoinfo</STRONG> composes single-line capabilities into an <STRONG>acsc</STRONG> string, and - discards <STRONG>GG</STRONG> and double-line capabilities with a warning diagnostic. + <STRONG>captoinfo</STRONG> composes single-line box-drawing capabilities into a <EM>terminfo</EM> + <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) string capability, and discards <STRONG>GG</STRONG> and double-line + capabilities with a warning diagnostic. - IBM's AIX has a <EM>terminfo</EM> facility descended from SVr1 <EM>terminfo</EM>, but - which is incompatible with the SVr4 format. <STRONG>captoinfo</STRONG> translates the - following AIX extensions. + AIX has a <EM>terminfo</EM> facility descended from SVr2 <EM>terminfo</EM>, but which is + incompatible with the SVr4 format. <STRONG>captoinfo</STRONG> translates the following + AIX extensions. - <STRONG>IBM</STRONG> <STRONG>XSI</STRONG> - ------------- - ksel kslt - kbtab kcbt - font0 s0ds - font1 s1ds - font2 s2ds - font3 s3ds + <STRONG>IBM</STRONG> <STRONG>X/Open</STRONG> + --------------- + ksel kslt + kbtab kcbt + font0 s0ds + font1 s1ds + font2 s2ds + font3 s3ds - Additionally, this program translates the AIX <STRONG>box1</STRONG> capability to an - <STRONG>acsc</STRONG> string. + It furthermore translates the AIX <STRONG>box1</STRONG> capability to an <STRONG>acs_chars</STRONG> + (<STRONG>acsc</STRONG>) string capability. - The HP-UX <EM>terminfo</EM> library supports two nonstandard <EM>terminfo</EM> - capabilities, <STRONG>meml</STRONG> (memory lock) and <STRONG>memu</STRONG> (memory unlock). <STRONG>captoinfo</STRONG> + The HP-UX <EM>terminfo</EM> library supports two nonstandard <EM>terminfo</EM> + capabilities: <STRONG>memory_lock</STRONG> (<STRONG>meml</STRONG>) and <STRONG>memory_unlock</STRONG> (<STRONG>memu</STRONG>). <STRONG>captoinfo</STRONG> discards these with a warning message. @@ -173,12 +170,15 @@ default <EM>termcap</EM> terminal capability database +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + This command is an SVr4 <EM>curses</EM> and <EM>ncurses</EM> extension. + + </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 7 (2009) describes <STRONG>tic</STRONG> briefly, but omits this - program. + X/Open Curses Issue 7 (2009) does not specify this command. - SVr4 systems provide <STRONG>captoinfo</STRONG> as a separate application from <STRONG>tic</STRONG>. Its - <STRONG>-v</STRONG> option does not accept a trace level argument <EM>n</EM>; repeat <STRONG>-v</STRONG> <EM>n</EM> times + SVr4 systems provide <EM>captoinfo</EM> as a separate application from <EM>tic</EM>. Its + <STRONG>-v</STRONG> option does not accept a trace level argument <EM>n</EM>; repeat <STRONG>-v</STRONG> <EM>n</EM> times instead. NetBSD does not provide this application. @@ -192,9 +192,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - -ncurses 6.5 2024-03-23 <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -206,6 +204,7 @@ ncurses 6.5 2024-03-23 <STRONG><A HREF </ul> </li> <li><a href="#h2-FILES">FILES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-AUTHORS">AUTHORS</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> diff --git a/doc/html/man/clear.1.html b/doc/html/man/clear.1.html index e7da4da4f41d..b47dca585286 100644 --- a/doc/html/man/clear.1.html +++ b/doc/html/man/clear.1.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: clear.1,v 1.48 2024/03/16 15:35:01 tom Exp @ + * @Id: clear.1,v 1.53 2025/04/05 21:56:26 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>clear 1 2024-03-16 ncurses 6.5 User commands</TITLE> +<TITLE>clear 1 2025-04-05 ncurses 6.6 User commands</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">clear 1 2024-03-16 ncurses 6.5 User commands</H1> +<H1 class="no-header">clear 1 2025-04-05 ncurses 6.6 User commands</H1> <PRE> <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG> User commands <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>clear</STRONG> - clear the terminal screen @@ -84,7 +82,7 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7 + Neither IEEE Std 1003.1/The Open Group Base Specifications Issue 7 (POSIX.1-2008) nor X/Open Curses Issue 7 documents <STRONG>clear</STRONG>. The latter documents <STRONG>tput</STRONG>, which could be used to replace this utility @@ -96,14 +94,14 @@ A <STRONG>clear</STRONG> command using the <EM>termcap</EM> database and library appeared in 2BSD (1979). Eighth Edition Unix (1985) later included it. - The commercial Unix arm of AT&T adapted a different BSD program (<STRONG>tset</STRONG>) - to make a new command, <STRONG>tput</STRONG>, and replaced the <STRONG>clear</STRONG> program with a + The commercial Unix arm of AT&T adapted a different BSD program (<STRONG>tset</STRONG>) + to make a new command, <STRONG>tput</STRONG>, and replaced the <STRONG>clear</STRONG> program with a shell script that called "<STRONG>tput</STRONG> <STRONG>clear</STRONG>". /usr/bin/tput ${1:+-T$1} clear 2> /dev/null exit - In 1989, when Keith Bostic revised the BSD <STRONG>tput</STRONG> command to make it + In 1989, when Keith Bostic revised the BSD <STRONG>tput</STRONG> command to make it similar to AT&T's <STRONG>tput</STRONG>, he added a <STRONG>clear</STRONG> shell script as well. exec tput clear @@ -139,16 +137,14 @@ to incorporate this extension. <STRONG>o</STRONG> In 2013, the <STRONG>E3</STRONG> capability was not exercised by "<STRONG>tput</STRONG> <STRONG>clear</STRONG>". That - oversight was addressed in 2016 by reorganizing <STRONG>tput</STRONG> to share its + oversight was addressed in 2016 by reorganizing <STRONG>tput</STRONG> to share its logic with <STRONG>clear</STRONG> and <STRONG>tset</STRONG>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>, <STRONG>xterm(1)</STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG> +ncurses 6.6 2025-04-05 <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_add_wch.3x.html b/doc/html/man/curs_add_wch.3x.html index 64c645d5ad02..8d535da07d36 100644 --- a/doc/html/man/curs_add_wch.3x.html +++ b/doc/html/man/curs_add_wch.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 2001-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,162 +28,280 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_add_wch.3x,v 1.62 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_add_wch.3x,v 1.125 2025/11/12 01:06:36 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_add_wch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_add_wch 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_add_wch 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_add_wch 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>add_wch</STRONG>, <STRONG>wadd_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, <STRONG>mvwadd_wch</STRONG>, <STRONG>echo_wchar</STRONG>, <STRONG>wecho_wchar</STRONG> - add - a <EM>curses</EM> complex character to a window and advance the cursor + a <EM>curses</EM> complex character to a window, possibly advancing the cursor </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>add_wch(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wadd_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvadd_wch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwadd_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>echo_wchar(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wecho_wchar(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>add_wch(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wadd_wch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvadd_wch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwadd_wch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>echo_wchar(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wecho_wchar(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> + + <EM>/*</EM> <EM>(integer)</EM> <EM>constants</EM> <EM>*/</EM> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_BLOCK;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_BOARD;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_BTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_BULLET;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_CKBOARD;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_DARROW;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_DEGREE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_DIAMOND;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_HLINE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_LANTERN;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_LARROW;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_LLCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_LRCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_LTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_PLMINUS;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_PLUS;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_RARROW;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_RTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_S1;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_S9;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_TTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_UARROW;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_ULCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_URCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_VLINE;</STRONG> + <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_GEQUAL;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_LEQUAL;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_NEQUAL;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_PI;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_S3;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_S7;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_STERLING;</STRONG> + <EM>/*</EM> <EM>extensions</EM> <EM>for</EM> <EM>thick</EM> <EM>lines</EM> <EM>*/</EM> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_T_BTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_T_HLINE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_T_LLCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_T_LRCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_T_LTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_T_PLUS;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_T_RTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_T_TTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_T_ULCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_T_URCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_T_VLINE;</STRONG> + <EM>/*</EM> <EM>extensions</EM> <EM>for</EM> <EM>double</EM> <EM>lines</EM> <EM>*/</EM> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_D_BTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_D_HLINE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_D_LLCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_D_LRCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_D_LTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_D_PLUS;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_D_RTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_D_TTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_D_ULCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_D_URCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>WACS_D_VLINE;</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> -</PRE><H3><a name="h3-add_wch">add_wch</a></H3><PRE> - The <STRONG>add_wch</STRONG>, <STRONG>wadd_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, and <STRONG>mvwadd_wch</STRONG> functions put the - complex character <EM>wch</EM> into the given window at its current position, - which is then advanced. These functions perform wrapping and special- - character processing as follows: - - <STRONG>o</STRONG> If <EM>wch</EM> refers to a spacing character, then any previous character - at that location is removed. A new character specified by <EM>wch</EM> is - placed at that location with rendition specified by <EM>wch</EM>. The - cursor then advances after this spacing character, to prepare for - writing the next character on the screen. - - The newly added spacing character is the base of the active complex - character. Subsequent non-spacing characters can be combined with - this base until another spacing character is written to the screen, - or the cursor is moved, e.g., using <STRONG>wmove</STRONG>. - - <STRONG>o</STRONG> If <EM>wch</EM> refers to a non-spacing character, it is appended to the - active complex character, retaining the previous characters at that - location. The rendition specified by <EM>wch</EM> is ignored. - - The cursor is not advanced after adding a non-spacing character. - Subsequent calls to add non-spacing characters will update the same - position. - - <STRONG>o</STRONG> If the character part of <EM>wch</EM> is a tab, newline, backspace or other - control character, the window is updated and the cursor moves as if - <STRONG>addch</STRONG> were called. - - -</PRE><H3><a name="h3-echo_wchar">echo_wchar</a></H3><PRE> - The <STRONG>echo_wchar</STRONG> function is functionally equivalent to a call to <STRONG>add_wch</STRONG> - followed by a call to <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>. Similarly, the <STRONG>wecho_wchar</STRONG> is - functionally equivalent to a call to <STRONG>wadd_wch</STRONG> followed by a call to - <STRONG>wrefresh</STRONG>. The knowledge that only a single character is being output - is taken into consideration and, for non-control characters, a - considerable performance gain might be seen by using the *<STRONG>echo</STRONG>* - functions instead of their equivalents. - - -</PRE><H3><a name="h3-Line-Graphics">Line Graphics</a></H3><PRE> - Like <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>, <STRONG>addch_wch</STRONG> accepts symbols which make it simple to draw - lines and other frequently used special characters. These symbols - correspond to the same VT100 line-drawing set as <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>. - - <STRONG>Unicode</STRONG> <STRONG>ASCII</STRONG> <STRONG>acsc</STRONG> - - - <STRONG>ACS</STRONG> <STRONG>Name</STRONG> <STRONG>Default</STRONG> <STRONG>Default</STRONG> <STRONG>Char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG> +</PRE><H3><a name="h3-wadd_wch">wadd_wch</a></H3><PRE> + <STRONG>wadd_wch</STRONG> writes the <EM>curses</EM> complex character <EM>wch</EM> to the window <EM>win</EM>, + then may advance the cursor position, analogously to the standard C + library's <STRONG>putwchar(3)</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this + function. + + Construct a <EM>curses</EM> complex character from a <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> with <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG>. + A <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> can be copied from place to place using <STRONG><A HREF="curs_in_wch.3x.html">win_wch(3x)</A></STRONG> and + <STRONG>wadd_wch</STRONG>. <EM>curses</EM> defines constants to aid the manipulation of + character attributes; see <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>. A complex character whose + only character component is a wide space, and whose only attribute is + <STRONG>WA_NORMAL</STRONG>, is a <EM>blank</EM> <EM>character</EM>, and therefore combines with the + window's background character; see <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>. + + Much behavior depends on whether the wide characters in <EM>wch</EM> are spacing + or non-spacing; see subsection "Complex Characters" below. + + <STRONG>o</STRONG> If <EM>wch</EM> contains a spacing character, then any character at the + cursor is first removed. The complex character <EM>wch</EM>, with its + attributes and color pair identifier, becomes the <EM>base</EM> of the + <EM>active</EM> <EM>complex</EM> <EM>character</EM>. + + <STRONG>o</STRONG> If <EM>wch</EM> contains only non-spacing characters, they are combined with + the active complex character. <EM>curses</EM> ignores its attributes and + color pair identifier, and does not advance the cursor. + + Further non-spacing characters added with <STRONG>wadd_wch</STRONG> are not written at + the new cursor position but combine with the active complex character + until another spacing character is written to the window or the cursor + is moved. + + If <EM>wch</EM> is a backspace, carriage return, line feed, or tab, the cursor + moves appropriately within the window. + + <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin + of a window, it does nothing. + + <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the same + line of the window. + + <STRONG>o</STRONG> Line feed does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then advances as if from the right + margin. + + <STRONG>o</STRONG> Tab advances the cursor to the next tab stop (possibly on the next + line); these are placed at every eighth column by default. + + Alter the tab interval with the <STRONG>TABSIZE</STRONG> extension; see + <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>. + + If <EM>wch</EM> is any other nonprintable character, <EM>curses</EM> draws it in + printable form using the same convention as <STRONG><A HREF="curs_util.3x.html">wunctrl(3x)</A></STRONG>. Calling + <STRONG><A HREF="curs_in_wch.3x.html">win_wch(3x)</A></STRONG> on the location of a nonprintable character does not + retrieve the character itself, but its <STRONG><A HREF="curs_util.3x.html">wunctrl(3x)</A></STRONG> representation. + + Adding spacing characters with <STRONG>wadd_wch</STRONG> causes it to wrap at the right + margin of the window: + + <STRONG>o</STRONG> If the cursor is not at the bottom of the scrolling region and + advancement occurs at the right margin, the cursor automatically + wraps to the beginning of the next line. + + <STRONG>o</STRONG> If the cursor is at the bottom of the scrolling region when + advancement occurs at the right margin, and <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is enabled + for <EM>win</EM>, the scrolling region scrolls up one line and the cursor + wraps as above. Otherwise, advancement and scrolling do not occur, + and <STRONG>wadd_wch</STRONG> returns <STRONG>ERR</STRONG>. + + A window's margins may coincide with the screen boundaries. This may + be a problem when <EM>ncurses</EM> updates the screen to match the curses + window. When their right and bottom margins coincide, <EM>ncurses</EM> uses + different strategies to handle the variations of scrolling and wrapping + at the lower-right corner by depending on the terminal capabilities: + + <STRONG>o</STRONG> If the terminal does not automatically wrap as characters are added + at the right margin (i.e., auto right margins), <EM>ncurses</EM> writes the + character directly. + + <STRONG>o</STRONG> If the terminal has auto right margins, but also has capabilities + for turning auto margins off and on, <EM>ncurses</EM> turns the auto margin + feature off temporarily when writing to the lower-right corner. + + <STRONG>o</STRONG> If the terminal has an insertion mode which can be turned off and + on, <EM>ncurses</EM> writes the character just before the lower-right + corner, and then inserts a character to push the update into the + corner. + + +</PRE><H3><a name="h3-wecho_wchar">wecho_wchar</a></H3><PRE> + <STRONG>echo_wchar</STRONG> and <STRONG>wecho_wchar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>add_wch</STRONG> + followed by (<STRONG>w</STRONG>)<STRONG>refresh</STRONG> on <STRONG>stdscr</STRONG> or the specified window. <EM>curses</EM> + interprets these functions as a hint that only a single (complex) + character is being output; for non-control characters, a considerable + performance gain may be enjoyed by employing them. + + +</PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE> + <EM>curses</EM> defines macros starting with <STRONG>WACS_</STRONG> that can be used with + <STRONG>wadd_wch</STRONG> to write line-drawing and other symbols to the screen. + <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> <EM>curses</EM> uses the ACS + default listed below if the terminal type lacks the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) + capability; that capability does not define a replacement for the + character; or if the terminal type and locale configuration require + Unicode to access these characters, but the library is unable to use + Unicode. The "acsc char" column corresponds to how the characters are + specified in the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) string capability, and the characters + in it may appear on the screen if the terminal type's database entry + incorrectly advertises ACS support. The name "ACS" originates in the + Alternate Character Set feature of the DEC VT100 terminal. + + <STRONG>Unicode</STRONG> <STRONG>ACS</STRONG> <STRONG>acsc</STRONG> + <STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG> ------------------------------------------------------------------------ - <STRONG>WACS_BLOCK</STRONG> 0x25ae # 0 solid square block - <STRONG>WACS_BOARD</STRONG> 0x2592 # h board of squares - <STRONG>WACS_BTEE</STRONG> 0x2534 + v bottom tee - <STRONG>WACS_BULLET</STRONG> 0x00b7 o ~ bullet - <STRONG>WACS_CKBOARD</STRONG> 0x2592 : a checker board (stipple) - <STRONG>WACS_DARROW</STRONG> 0x2193 v . arrow pointing down - <STRONG>WACS_DEGREE</STRONG> 0x00b0 ' f degree symbol - <STRONG>WACS_DIAMOND</STRONG> 0x25c6 + ` diamond - <STRONG>WACS_GEQUAL</STRONG> 0x2265 > > greater-than-or-equal-to - <STRONG>WACS_HLINE</STRONG> 0x2500 - q horizontal line - <STRONG>WACS_LANTERN</STRONG> 0x2603 # i lantern symbol - <STRONG>WACS_LARROW</STRONG> 0x2190 < , arrow pointing left - <STRONG>WACS_LEQUAL</STRONG> 0x2264 < y less-than-or-equal-to - <STRONG>WACS_LLCORNER</STRONG> 0x2514 + m lower left-hand corner - <STRONG>WACS_LRCORNER</STRONG> 0x2518 + j lower right-hand corner - <STRONG>WACS_LTEE</STRONG> 0x2524 + t left tee - <STRONG>WACS_NEQUAL</STRONG> 0x2260 ! | not-equal - <STRONG>WACS_PI</STRONG> 0x03c0 * { greek pi - <STRONG>WACS_PLMINUS</STRONG> 0x00b1 # g plus/minus - <STRONG>WACS_PLUS</STRONG> 0x253c + n plus - <STRONG>WACS_RARROW</STRONG> 0x2192 > + arrow pointing right - <STRONG>WACS_RTEE</STRONG> 0x251c + u right tee - <STRONG>WACS_S1</STRONG> 0x23ba - o scan line 1 - <STRONG>WACS_S3</STRONG> 0x23bb - p scan line 3 - <STRONG>WACS_S7</STRONG> 0x23bc - r scan line 7 - <STRONG>WACS_S9</STRONG> 0x23bd _ s scan line 9 - <STRONG>WACS_STERLING</STRONG> 0x00a3 f } pound-sterling symbol - <STRONG>WACS_TTEE</STRONG> 0x252c + w top tee - <STRONG>WACS_UARROW</STRONG> 0x2191 ^ - arrow pointing up - <STRONG>WACS_ULCORNER</STRONG> 0x250c + l upper left-hand corner - <STRONG>WACS_URCORNER</STRONG> 0x2510 + k upper right-hand corner - <STRONG>WACS_VLINE</STRONG> 0x2502 | x vertical line - - The wide-character configuration of <EM>ncurses</EM> also defines symbols for - thick lines (<STRONG>acsc</STRONG> "J" to "V"): + <STRONG>WACS_BLOCK</STRONG> U+25ae # 0 solid square block + <STRONG>WACS_BOARD</STRONG> U+2592 # h board of squares + <STRONG>WACS_BTEE</STRONG> U+2534 + v bottom tee + <STRONG>WACS_BULLET</STRONG> U+00b7 o ~ bullet + <STRONG>WACS_CKBOARD</STRONG> U+2592 : a checker board (stipple) + <STRONG>WACS_DARROW</STRONG> U+2193 v . arrow pointing down + <STRONG>WACS_DEGREE</STRONG> U+00b0 ' f degree symbol + <STRONG>WACS_DIAMOND</STRONG> U+25c6 + ` diamond + <STRONG>WACS_GEQUAL</STRONG> U+2265 > > greater-than-or-equal-to + <STRONG>WACS_HLINE</STRONG> U+2500 - q horizontal line + <STRONG>WACS_LANTERN</STRONG> U+2603 # i lantern symbol + <STRONG>WACS_LARROW</STRONG> U+2190 < , arrow pointing left + <STRONG>WACS_LEQUAL</STRONG> U+2264 < y less-than-or-equal-to + <STRONG>WACS_LLCORNER</STRONG> U+2514 + m lower left-hand corner + <STRONG>WACS_LRCORNER</STRONG> U+2518 + j lower right-hand corner + <STRONG>WACS_LTEE</STRONG> U+2524 + t left tee + <STRONG>WACS_NEQUAL</STRONG> U+2260 ! | not-equal + <STRONG>WACS_PI</STRONG> U+03c0 * { greek pi + <STRONG>WACS_PLMINUS</STRONG> U+00b1 # g plus/minus + <STRONG>WACS_PLUS</STRONG> U+253c + n plus + <STRONG>WACS_RARROW</STRONG> U+2192 > + arrow pointing right + <STRONG>WACS_RTEE</STRONG> U+251c + u right tee + <STRONG>WACS_S1</STRONG> U+23ba - o scan line 1 + <STRONG>WACS_S3</STRONG> U+23bb - p scan line 3 + <STRONG>WACS_S7</STRONG> U+23bc - r scan line 7 + <STRONG>WACS_S9</STRONG> U+23bd _ s scan line 9 + <STRONG>WACS_STERLING</STRONG> U+00a3 f } pound-sterling symbol + <STRONG>WACS_TTEE</STRONG> U+252c + w top tee + <STRONG>WACS_UARROW</STRONG> U+2191 ^ - arrow pointing up + <STRONG>WACS_ULCORNER</STRONG> U+250c + l upper left-hand corner + <STRONG>WACS_URCORNER</STRONG> U+2510 + k upper right-hand corner + <STRONG>WACS_VLINE</STRONG> U+2502 | x vertical line + + The <EM>ncurses</EM> wide API also defines symbols for thick lines (<STRONG>acsc</STRONG> "J" + through "N", "T" through "X", and "Q"): <STRONG>Unicode</STRONG> <STRONG>ASCII</STRONG> <STRONG>acsc</STRONG> <STRONG>ACS</STRONG> <STRONG>Name</STRONG> <STRONG>Default</STRONG> <STRONG>Default</STRONG> <STRONG>Char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG> ------------------------------------------------------------------------ - <STRONG>WACS_T_BTEE</STRONG> 0x253b + V thick tee pointing up - <STRONG>WACS_T_HLINE</STRONG> 0x2501 - Q thick horizontal line - <STRONG>WACS_T_LLCORNER</STRONG> 0x2517 + M thick lower left corner - <STRONG>WACS_T_LRCORNER</STRONG> 0x251b + J thick lower right corner - <STRONG>WACS_T_LTEE</STRONG> 0x252b + T thick tee pointing right - <STRONG>WACS_T_PLUS</STRONG> 0x254b + N thick large plus - <STRONG>WACS_T_RTEE</STRONG> 0x2523 + U thick tee pointing left - <STRONG>WACS_T_TTEE</STRONG> 0x2533 + W thick tee pointing down - <STRONG>WACS_T_ULCORNER</STRONG> 0x250f + L thick upper left corner - <STRONG>WACS_T_URCORNER</STRONG> 0x2513 + K thick upper right corner - <STRONG>WACS_T_VLINE</STRONG> 0x2503 | X thick vertical line - - and for double-lines (<STRONG>acsc</STRONG> "A" to "I"): + <STRONG>WACS_T_BTEE</STRONG> U+253b + V thick tee pointing up + <STRONG>WACS_T_HLINE</STRONG> U+2501 - Q thick horizontal line + <STRONG>WACS_T_LLCORNER</STRONG> U+2517 + M thick lower left corner + <STRONG>WACS_T_LRCORNER</STRONG> U+251b + J thick lower right corner + <STRONG>WACS_T_LTEE</STRONG> U+252b + T thick tee pointing right + <STRONG>WACS_T_PLUS</STRONG> U+254b + N thick large plus + <STRONG>WACS_T_RTEE</STRONG> U+2523 + U thick tee pointing left + <STRONG>WACS_T_TTEE</STRONG> U+2533 + W thick tee pointing down + <STRONG>WACS_T_ULCORNER</STRONG> U+250f + L thick upper left corner + <STRONG>WACS_T_URCORNER</STRONG> U+2513 + K thick upper right corner + <STRONG>WACS_T_VLINE</STRONG> U+2503 | X thick vertical line + + and for double lines (<STRONG>acsc</STRONG> "A" through "I", plus "R" and "Y"): <STRONG>Unicode</STRONG> <STRONG>ASCII</STRONG> <STRONG>acsc</STRONG> <STRONG>ACS</STRONG> <STRONG>Name</STRONG> <STRONG>Default</STRONG> <STRONG>Default</STRONG> <STRONG>Char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG> ------------------------------------------------------------------------ - <STRONG>WACS_D_BTEE</STRONG> 0x2569 + H double tee pointing up - <STRONG>WACS_D_HLINE</STRONG> 0x2550 - R double horizontal line - <STRONG>WACS_D_LLCORNER</STRONG> 0x255a + D double lower left corner - <STRONG>WACS_D_LRCORNER</STRONG> 0x255d + A double lower right corner - <STRONG>WACS_D_LTEE</STRONG> 0x2560 + F double tee pointing right - <STRONG>WACS_D_PLUS</STRONG> 0x256c + E double large plus - <STRONG>WACS_D_RTEE</STRONG> 0x2563 + G double tee pointing left - - <STRONG>WACS_D_TTEE</STRONG> 0x2566 + I double tee pointing down - <STRONG>WACS_D_ULCORNER</STRONG> 0x2554 + C double upper left corner - <STRONG>WACS_D_URCORNER</STRONG> 0x2557 + B double upper right corner - <STRONG>WACS_D_VLINE</STRONG> 0x2551 | Y double vertical line + <STRONG>WACS_D_BTEE</STRONG> U+2569 + H double tee pointing up + <STRONG>WACS_D_HLINE</STRONG> U+2550 - R double horizontal line + <STRONG>WACS_D_LLCORNER</STRONG> U+255a + D double lower left corner + <STRONG>WACS_D_LRCORNER</STRONG> U+255d + A double lower right corner + <STRONG>WACS_D_LTEE</STRONG> U+2560 + F double tee pointing right + <STRONG>WACS_D_PLUS</STRONG> U+256c + E double large plus + <STRONG>WACS_D_RTEE</STRONG> U+2563 + G double tee pointing left + <STRONG>WACS_D_TTEE</STRONG> U+2566 + I double tee pointing down + <STRONG>WACS_D_ULCORNER</STRONG> U+2554 + C double upper left corner + <STRONG>WACS_D_URCORNER</STRONG> U+2557 + B double upper right corner + <STRONG>WACS_D_VLINE</STRONG> U+2551 | Y double vertical line Unicode's descriptions for these characters differs slightly from <EM>ncurses</EM>, by introducing the term "light" (along with less important @@ -198,75 +316,85 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success. - - X/Open Curses does not specify any error conditions. This - implementation returns an error + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - <STRONG>o</STRONG> if the window pointer is null or + In <EM>ncurses</EM>, these functions fail if - <STRONG>o</STRONG> if it is not possible to add a complete character in the window. + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - The latter may be due to different causes: + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, - <STRONG>o</STRONG> If <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not enabled, writing a character at the lower - right margin succeeds. However, an error is returned because it is - not possible to wrap to a new line. + <STRONG>o</STRONG> wrapping to a new line is impossible because <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> has not + been called on <EM>win</EM> (or <STRONG>stdscr</STRONG>, as applicable) when writing to its + bottom right location is attempted, or - <STRONG>o</STRONG> If an error is detected when converting a multibyte character to a - sequence of bytes, or if it is not possible to add all of the - resulting bytes in the window, an error is returned. + <STRONG>o</STRONG> it is not possible to add a complete character at the cursor + position. - Functions prefixed with "mv" first perform cursor movement and fail if + Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that <STRONG>add_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, <STRONG>mvwadd_wch</STRONG>, and <STRONG>echo_wchar</STRONG> may be macros. + <STRONG>add_wch</STRONG>, <STRONG>mvadd_wch</STRONG>, <STRONG>mvwadd_wch</STRONG>, and <STRONG>echo_wchar</STRONG> may be implemented as + macros. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + The symbols <EM>WACS</EM><STRONG>_</STRONG><EM>S3</EM>, <EM>WACS</EM><STRONG>_</STRONG><EM>S7</EM>, <EM>WACS</EM><STRONG>_</STRONG><EM>LEQUAL</EM>, <EM>WACS</EM><STRONG>_</STRONG><EM>GEQUAL</EM>, <EM>WACS</EM><STRONG>_</STRONG><EM>PI</EM>, + <EM>WACS</EM><STRONG>_</STRONG><EM>NEQUAL</EM>, and <EM>WACS</EM><STRONG>_</STRONG><EM>STERLING</EM> are not standard. However, many + publicly available <EM>terminfo</EM> entries include <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) + capabilities in which their key characters (<STRONG>pryz{|}</STRONG>) are embedded, and + a second-hand list of their character descriptions has come to light. + The <EM>ncurses</EM> developers invented WACS-prefixed names for them. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. The defaults - specified for line-drawing characters apply in the POSIX locale. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + These functions are described in X/Open Curses Issue 4. It specifies + no error conditions for them. -</PRE><H3><a name="h3-WACS-Symbols">WACS Symbols</a></H3><PRE> - X/Open Curses makes it clear that the WACS_ symbols should be defined - as a pointer to <STRONG>cchar_t</STRONG> data, e.g., in the discussion of <STRONG>border_set</STRONG>. A - few implementations are problematic: + The defaults specified for forms-drawing characters apply in the POSIX + locale. X/Open Curses makes it clear that the WACS_ symbols should be + defined as a pointer to <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> data, e.g., in the discussion of + <EM>border</EM><STRONG>_</STRONG><EM>set</EM>. A few implementations are problematic: - <STRONG>o</STRONG> NetBSD curses defines the symbols as a <STRONG>wchar_t</STRONG> within a <STRONG>cchar_t</STRONG>. + <STRONG>o</STRONG> NetBSD <EM>curses</EM> defines the symbols as a <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> within a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. - <STRONG>o</STRONG> HP-UX curses equates some of the <STRONG>ACS_</STRONG> symbols to the analogous - <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters. The + <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <EM>ACS</EM><STRONG>_</STRONG> symbols to the analogous + <EM>WACS</EM><STRONG>_</STRONG> symbols as if the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters. The misdefined symbols are the arrows and other symbols which are not used for line-drawing. X/Open Curses does not specify symbols for thick- or double-lines. - SVr4 curses implementations defined their line-drawing symbols in terms - of intermediate symbols. This implementation extends those symbols, - providing new definitions which are not in the SVr4 implementations. - - Not all Unicode-capable terminals provide support for VT100-style - alternate character sets (i.e., the <STRONG>acsc</STRONG> capability), with their - corresponding line-drawing characters. X/Open Curses did not address - the aspect of integrating Unicode with line-drawing characters. - Existing implementations of Unix curses (AIX, HP-UX, Solaris) use only - the <STRONG>acsc</STRONG> character-mapping to provide this feature. As a result, those - implementations can only use single-byte line-drawing characters. - <EM>ncurses</EM> 5.3 (2002) provided a table of Unicode values to solve these - problems. NetBSD curses incorporated that table in 2010. - - In this implementation, the Unicode values are used instead of the - terminal description's <STRONG>acsc</STRONG> mapping as discussed in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> for the - environment variable <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM>. In contrast, for the same - cases, the line-drawing characters described in <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG> will use only - the ASCII default values. + SVr4 <EM>curses</EM> implementations defined their line-drawing symbols in terms + of intermediate symbols. <EM>ncurses</EM> extends those symbols, providing new + definitions not found in SVr4 implementations. + + Not all Unicode-capable terminals provide support for VT100-style + alternate character sets (i.e., the <EM>acsc</EM><STRONG>_</STRONG><EM>chars</EM> (<STRONG>acsc</STRONG>) capability), with + their corresponding line-drawing characters. X/Open Curses did not + address the aspect of integrating Unicode with line-drawing characters. + Existing implementations of System V <EM>curses</EM> (AIX, HP-UX, Solaris) use + only the <EM>acsc</EM><STRONG>_</STRONG><EM>chars</EM> (<STRONG>acsc</STRONG>) character-mapping to provide this feature. + As a result, those implementations can use only single-byte line- + drawing characters. <EM>ncurses</EM> 5.3 (2002) provided a table of Unicode + values to solve these problems. NetBSD <EM>curses</EM> incorporated that table + in 2010. + + <EM>ncurses</EM> uses the Unicode values instead of the terminal type + description's <EM>acsc</EM><STRONG>_</STRONG><EM>chars</EM> (<STRONG>acsc</STRONG>) mapping as discussed in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> for + the environment variable <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM>. In contrast, for the + same cases, the line-drawing characters described in <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG> will use + only the ASCII default values. Having Unicode available does not solve all of the problems with line- - drawing for curses: + drawing for <EM>curses</EM>: - <STRONG>o</STRONG> The closest Unicode equivalents to the VT100 graphics <EM>S1</EM>, <EM>S3</EM>, <EM>S7</EM> + <STRONG>o</STRONG> The closest Unicode equivalents to the VT100 graphics <EM>S1</EM>, <EM>S3</EM>, <EM>S7</EM>, and <EM>S9</EM> frequently are not displayed at the regular intervals which the terminal used. @@ -277,45 +405,58 @@ Lacking documentation, most readers assume that a <EM>storm</EM> <EM>lantern</EM> was intended. But there are several possibilities, all with problems. - Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and - U+1F3EE. Those were not available in 2002, and are irrelevant - since they lie outside the BMP and as a result are not generally - available in terminals. They are not storm lanterns, in any case. + Unicode 6.0 (2010) does provide two lantern symbols: U+1F383 and + U+1F3EE. Those were not available in 2002, and are irrelevant + since they lie outside the Basic Multilingual Plane and as a result + are unavailable on many terminals. They are not storm lanterns, in + any case. Most <EM>storm</EM> <EM>lanterns</EM> have a tapering glass chimney (to guard against tipping); some have a wire grid protecting the chimney. - For the tapering appearance, U+2603 was adequate. In use on a + For the tapering appearance, U+2603 was adequate. In use on a terminal, no one can tell what the image represents. Unicode calls it a snowman. Others have suggested these alternatives: <section> U+00A7 (section - mark), <Theta> U+0398 (theta), <Phi> U+03A6 (phi), <delta> U+03B4 + mark), <Theta> U+0398 (theta), <Phi> U+03A6 (phi), <delta> U+03B4 (delta), U+2327 (x in a rectangle), U+256C (forms double vertical and horizontal), and U+2612 (ballot box with x). </PRE><H3><a name="h3-Complex-Characters">Complex Characters</a></H3><PRE> - The complex character type <STRONG>cchar_t</STRONG> can store more than one wide - character (<STRONG>wchar_t</STRONG>). The X/Open Curses description does not mention - this possibility, describing only the cases where <EM>wch</EM> is a spacing - character or a non-spacing character. + The complex character type <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> can store more than one wide + character (<EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>). X/Open Curses does not mention this possibility, + specifying behavior only where <EM>wch</EM> is a single character, either + spacing or non-spacing. - This implementation assumes that <EM>wch</EM> is constructed using <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG>, - and in turn that the result + <EM>ncurses</EM> assumes that <EM>wch</EM> is constructed using <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG>, and in turn + that the result - <STRONG>o</STRONG> contains at most one spacing character in the beginning of its list - of wide characters, and zero or more non-spacing characters or + <STRONG>o</STRONG> contains at most one spacing character at the beginning of its list + of wide characters, and zero or more non-spacing characters, or - <STRONG>o</STRONG> may hold one non-spacing character. + <STRONG>o</STRONG> holds one non-spacing character. In the latter case, <EM>ncurses</EM> adds the non-spacing character to the - active (base) spacing character. + active complex character. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + X/Open Curses Issue 4 (1995) initially specified these functions. The + System V Interface Definition (SVID) Version 4 of the same year + specified functions named <EM>waddwch</EM> (and the usual variants), <EM>echowchar</EM>, + and <EM>wechowchar</EM>. These were later additions to SVr4.<EM>x</EM>, not appearing in + the first SVr4 (1989). They differed from X/Open's later <EM>wadd</EM><STRONG>_</STRONG><EM>wch</EM> and + <EM>wecho</EM><STRONG>_</STRONG><EM>wchar</EM> in that they each took an argument of type <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> instead + of <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. SVID defined no <EM>WACS</EM><STRONG>_</STRONG> symbols. + X/Open Curses Issue 4 also defined many of the <EM>WACS</EM><STRONG>_</STRONG> constants, + excepting <EM>WACS</EM><STRONG>_</STRONG><EM>GEQUAL</EM>, <EM>WACS</EM><STRONG>_</STRONG><EM>LEQUAL</EM>, <EM>WACS</EM><STRONG>_</STRONG><EM>NEQUAL</EM>, <EM>WACS</EM><STRONG>_</STRONG><EM>PI</EM>, <EM>WACS</EM><STRONG>_</STRONG><EM>S3</EM>, + <EM>WACS</EM><STRONG>_</STRONG><EM>S7</EM>, and <EM>WACS</EM><STRONG>_</STRONG><EM>STERLING</EM>; and those for drawing thick and double + lines. -</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE> - The <STRONG>TABSIZE</STRONG> variable is implemented in SVr4 and other versions of - <EM>curses</EM>, but is not specified by X/Open Curses (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>). + <EM>ncurses</EM> 5.3 (2002) furnished the remaining <EM>WACS</EM><STRONG>_</STRONG> constants. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> @@ -323,12 +464,10 @@ its non-wide-character configuration. <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, - <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, - <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putwc(3)</STRONG> - - + <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, + <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putwc(3)</STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -336,20 +475,20 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="c <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a> <ul> -<li><a href="#h3-add_wch">add_wch</a></li> -<li><a href="#h3-echo_wchar">echo_wchar</a></li> -<li><a href="#h3-Line-Graphics">Line Graphics</a></li> +<li><a href="#h3-wadd_wch">wadd_wch</a></li> +<li><a href="#h3-wecho_wchar">wecho_wchar</a></li> +<li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li> </ul> </li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a> <ul> -<li><a href="#h3-WACS-Symbols">WACS Symbols</a></li> <li><a href="#h3-Complex-Characters">Complex Characters</a></li> -<li><a href="#h3-TABSIZE">TABSIZE</a></li> </ul> </li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_add_wchstr.3x.html b/doc/html/man/curs_add_wchstr.3x.html index f554061d849d..46d478511810 100644 --- a/doc/html/man/curs_add_wchstr.3x.html +++ b/doc/html/man/curs_add_wchstr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 2002-2012,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,93 +27,101 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_add_wchstr.3x,v 1.39 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_add_wchstr.3x,v 1.61 2025/10/21 00:06:34 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_add_wchstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_add_wchstr 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_add_wchstr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_add_wchstr 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>add_wchstr</STRONG>, <STRONG>add_wchnstr</STRONG>, <STRONG>wadd_wchstr</STRONG>, <STRONG>wadd_wchnstr</STRONG>, <STRONG>mvadd_wchstr</STRONG>, - <STRONG>mvadd_wchnstr</STRONG>, <STRONG>mvwadd_wchstr</STRONG>, <STRONG>mvwadd_wchnstr</STRONG> - add a <EM>curses</EM> complex + <STRONG>add_wchstr</STRONG>, <STRONG>wadd_wchstr</STRONG>, <STRONG>mvadd_wchstr</STRONG>, <STRONG>mvwadd_wchstr</STRONG>, <STRONG>add_wchnstr</STRONG>, + <STRONG>wadd_wchnstr</STRONG>, <STRONG>mvadd_wchnstr</STRONG>, <STRONG>mvwadd_wchnstr</STRONG> - add a <EM>curses</EM> complex character string to a window </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>add_wchstr(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wadd_wchstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvadd_wchstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwadd_wchstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>add_wchstr(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wadd_wchstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvadd_wchstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwadd_wchstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>add_wchnstr(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wadd_wchnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvadd_wchnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwadd_wchnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>add_wchnstr(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wadd_wchnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvadd_wchnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwadd_wchnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These functions copy the (null-terminated) array of complex characters - <EM>wchstr</EM> into the window image structure starting at the current cursor - position. - - The four functions with <EM>n</EM> as the last argument copy at most <EM>n</EM> elements, - but no more than will fit on the line. If <STRONG>n</STRONG>=<STRONG>-1</STRONG> then the whole array is - copied, to the maximum number of characters that will fit on the line. + <STRONG>wadd_wchstr</STRONG> copies the string of complex characters <EM>wchstr</EM> to the + window <EM>win</EM>. A null complex character terminates the string. If a + complex character does not completely fit at the end of the line, + <EM>curses</EM> fills its remaining cells with the window's background + character; see <STRONG><A HREF="curs_bkgrnd.3x.html">bkgrnd(3x)</A></STRONG>. <STRONG>wadd_wchnstr</STRONG> does the same, but copies at + most <EM>n</EM> characters, or as many as possible if <EM>n</EM> is <STRONG>-1</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> + describes the variants of these functions. - The window cursor is <EM>not</EM> advanced. These functions are faster than - <STRONG>waddnstr</STRONG>. On the other hand: + Because these functions do not call <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> internally, they are + faster than <STRONG><A HREF="curs_addwstr.3x.html">waddwstr(3x)</A></STRONG> and <STRONG><A HREF="curs_addwstr.3x.html">waddnwstr(3x)</A></STRONG>. On the other hand, they - <STRONG>o</STRONG> they do not perform checking (such as for the newline, backspace, - or carriage return characters), + <STRONG>o</STRONG> do not treat the backspace, carriage return, or line feed + characters specially; - <STRONG>o</STRONG> they do not advance the current cursor position, + <STRONG>o</STRONG> do not represent unprintable characters with <STRONG><A HREF="curs_util.3x.html">wunctrl(3x)</A></STRONG>; - <STRONG>o</STRONG> they do not expand other control characters to ^-escapes, and + <STRONG>o</STRONG> do not update the cursor position to follow the last character + written; and - <STRONG>o</STRONG> they truncate the string if it crosses the right margin, rather - than wrapping it around to the new line. - - These functions end successfully on encountering a null <STRONG>cchar_t</STRONG>, or - when they have filled the current line. If a complex character cannot - completely fit at the end of the current line, the remaining columns - are filled with the background character and rendition. + <STRONG>o</STRONG> truncate the string at the window's right margin, rather than + wrapping it to the next line and potentially scrolling. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All functions return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. + + In <EM>ncurses</EM>, these functions fail if - X/Open Curses does not specify any error conditions. This - implementation returns an error + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> if the <EM>win</EM> parameter is null or + <STRONG>o</STRONG> <EM>wchstr</EM> is a null pointer, or - <STRONG>o</STRONG> if the <EM>wchstr</EM> parameter is null. + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All functions except <STRONG>wadd_wchnstr</STRONG> may be macros. + All of these functions except <STRONG>wadd_wchnstr</STRONG> may be implemented as + macros. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + X/Open Curses Issue 4 (1995) initially specified these functions. The + System V Interface Definition Version 4 of the same year specified + functions named <EM>waddwchstr</EM> and <EM>waddwchnstr</EM> (and the usual variants). + These were later additions to SVr4.<EM>x</EM>, not appearing in the first SVr4 + (1989). They differed from X/Open's later <EM>wadd</EM><STRONG>_</STRONG><EM>wchstr</EM> and <EM>wadd</EM><STRONG>_</STRONG><EM>wchnstr</EM> + in that they each took an argument of type <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> instead of <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> @@ -122,9 +130,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -134,6 +140,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="curs <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_addch.3x.html b/doc/html/man/curs_addch.3x.html index 0a0622e39af3..c8227c421763 100644 --- a/doc/html/man/curs_addch.3x.html +++ b/doc/html/man/curs_addch.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_addch.3x,v 1.85 2024/04/20 19:03:47 tom Exp @ + * @Id: curs_addch.3x,v 1.144 2025/11/12 01:04:12 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_addch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_addch 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_addch 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_addch 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>addch</STRONG>, <STRONG>waddch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, <STRONG>echochar</STRONG>, <STRONG>wechochar</STRONG> - add a <EM>curses</EM> character to a window and advance the cursor @@ -56,28 +54,68 @@ <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> <STRONG>int</STRONG> <STRONG>addch(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>waddch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>waddch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>mvaddch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwaddch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwaddch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>echochar(const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wechochar(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wechochar(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> + + <EM>/*</EM> <EM>(integer)</EM> <EM>constants</EM> <EM>*/</EM> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BLOCK;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BOARD;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_BULLET;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_CKBOARD;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_DARROW;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_DEGREE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_DIAMOND;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_HLINE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LANTERN;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LARROW;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LLCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LRCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_PLMINUS;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_PLUS;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_RARROW;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_RTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S1;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S9;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_TTEE;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_UARROW;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_ULCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_URCORNER;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_VLINE;</STRONG> + <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_GEQUAL;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_LEQUAL;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_NEQUAL;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_PI;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S3;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_S7;</STRONG> + /* <EM>...</EM> <EM>*/</EM> <STRONG>ACS_STERLING;</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> -</PRE><H3><a name="h3-Adding-Characters">Adding Characters</a></H3><PRE> - <STRONG>waddch</STRONG> puts the character <EM>ch</EM> at the cursor position of window <EM>win</EM>, then - advances the cursor position, analogously to the standard C library's +</PRE><H3><a name="h3-waddch">waddch</a></H3><PRE> + <STRONG>waddch</STRONG> writes the <EM>curses</EM> character <EM>ch</EM> to the window <EM>win</EM>, then advances + the cursor position, analogously to the standard C library's <STRONG>putchar(3)</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function. - If advancement occurs at the right margin, - - <STRONG>o</STRONG> the cursor automatically wraps to the beginning of the next line; - and + Construct a <EM>curses</EM> character from a <EM>char</EM> by assignment or typecast. + Subsection "Video Attributes" of <STRONG><A HREF="curs_attr.3x.html">attron(3x)</A></STRONG> describes how to manipulate + its attributes and color pair. (A color pair selection is not honored + unless initialized; see <STRONG><A HREF="curs_color.3x.html">start_color(3x)</A></STRONG>.) - <STRONG>o</STRONG> at the bottom of the current scrolling region, and if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> - is enabled for <EM>win</EM>, the scrolling region scrolls up one line. + The object or expression <EM>ch</EM> may contain attributes and/or a color pair + identifier. (A <EM>chtype</EM> can be copied from place to place using + <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> and <STRONG>waddch</STRONG>.) <EM>curses</EM> defines constants to aid the + manipulation of character attributes; see <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>. A <EM>ch</EM> whose + character component is a space, and whose only attribute is <STRONG>A_NORMAL</STRONG>, + is a <EM>blank</EM> <EM>character</EM>, and therefore combines with the window's + background character; see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>. If <EM>ch</EM> is a backspace, carriage return, line feed, or tab, the cursor moves appropriately within the window. @@ -85,52 +123,78 @@ <STRONG>o</STRONG> Backspace moves the cursor one character left; at the left margin of a window, it does nothing. - <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the current + <STRONG>o</STRONG> Carriage return moves the cursor to the left margin on the same line of the window. - <STRONG>o</STRONG> Line feed does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then moves the cursor to the left - margin on the next line of the window, and if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is - enabled for <EM>win</EM>, scrolls the window if the cursor was already on - the last line. + <STRONG>o</STRONG> Line feed does a <STRONG><A HREF="curs_clear.3x.html">clrtoeol(3x)</A></STRONG>, then advances as if from the right + margin. <STRONG>o</STRONG> Tab advances the cursor to the next tab stop (possibly on the next - line); these are placed at every eighth column by default. Alter - the tab interval with the <STRONG>TABSIZE</STRONG> extension; see + line); these are placed at every eighth column by default. + + Alter the tab interval with the <STRONG>TABSIZE</STRONG> extension; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>. - If <EM>ch</EM> is any other nonprintable character, it is drawn in printable - form, using the same convention as <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>. + If <EM>ch</EM> is any other nonprintable character, <EM>curses</EM> draws it in printable + form using the same convention as <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>. Calling <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> on the + location of a nonprintable character does not return the character + itself, but its <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> representation. + + Adding printable characters with <STRONG>waddch</STRONG> causes it to wrap at the right + margin of the window: + + <STRONG>o</STRONG> If the cursor is not at the bottom of the scrolling region and + advancement occurs at the right margin, the cursor automatically + wraps to the beginning of the next line. + + <STRONG>o</STRONG> If the cursor is at the bottom of the scrolling region when + advancement occurs at the right margin, and <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is enabled + for <EM>win</EM>, the scrolling region scrolls up one line and the cursor + wraps as above. Otherwise, advancement and scrolling do not occur, + and <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG>. + + A window's margins may coincide with the screen boundaries. This may + be a problem when <EM>ncurses</EM> updates the screen to match the curses + window. When their right and bottom margins coincide, <EM>ncurses</EM> uses + different strategies to handle the variations of scrolling and wrapping + at the lower-right corner by depending on the terminal capabilities: + + <STRONG>o</STRONG> If the terminal does not automatically wrap as characters are added + at the right margin (i.e., auto right margins), <EM>ncurses</EM> writes the + character directly. - Calling <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> on the location of a nonprintable character does not - return the character itself, but its <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> representation. + <STRONG>o</STRONG> If the terminal has auto right margins, but also has capabilities + for turning auto margins off and on, <EM>ncurses</EM> turns the auto margin + feature off temporarily when writing to the lower-right corner. - <EM>ch</EM> may contain rendering and/or color attributes, and others can be - combined with the parameter by logically "or"ing with it. (A character - with its attributes can be copied from place to place using <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG> - and <STRONG>waddch</STRONG>.) See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> for values of predefined video - attribute constants that can be usefully "or"ed with characters. + <STRONG>o</STRONG> If the terminal has an insertion mode which can be turned off and + on, <EM>ncurses</EM> writes the character just before the lower-right + corner, and then inserts a character to push the update into the + corner. -</PRE><H3><a name="h3-Echoing-Characters">Echoing Characters</a></H3><PRE> +</PRE><H3><a name="h3-wechochar">wechochar</a></H3><PRE> <STRONG>echochar</STRONG> and <STRONG>wechochar</STRONG> are equivalent to calling (<STRONG>w</STRONG>)<STRONG>addch</STRONG> followed by - (<STRONG>w</STRONG>)<STRONG>refresh</STRONG>. <EM>curses</EM> interprets these functions as a hint that only a - single character is being output; for non-control characters, a - considerable performance gain may be enjoyed by employing them. + (<STRONG>w</STRONG>)<STRONG>refresh</STRONG> on <STRONG>stdscr</STRONG> or the specified window. <EM>curses</EM> interprets these + functions as a hint to its optimizer that only a single character cell + in the window is being altered between refreshes; for non-control + characters, a considerable performance gain may be enjoyed by employing + them. </PRE><H3><a name="h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></H3><PRE> - <EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG> - to write line-drawing and other special characters to the screen. - <EM>ncurses</EM> terms these <EM>forms-drawing</EM> <EM>characters.</EM> The ACS default listed - below is used if the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) <EM>terminfo</EM> capability does not - define a terminal-specific replacement for it, or if the terminal and - locale configuration requires Unicode to access these characters but - the library is unable to use Unicode. The "acsc char" column - corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> string - capability, and the characters in it may appear on the screen if the - terminal's database entry incorrectly advertises ACS support. The name - "ACS" originates in the Alternate Character Set feature of the DEC - VT100 terminal. + <EM>curses</EM> defines macros starting with <STRONG>ACS_</STRONG> that can be used with <STRONG>waddch</STRONG> + to write line-drawing and other symbols to the screen. <EM>ncurses</EM> terms + these <EM>forms-drawing</EM> <EM>characters.</EM> <EM>curses</EM> uses the ACS default listed + below if the terminal type lacks the <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) capability; that + capability does not define a replacement for the character; or if the + terminal type and locale configuration require Unicode to access these + characters, but the library is unable to use Unicode. The "acsc char" + column corresponds to how the characters are specified in the <STRONG>acs_chars</STRONG> + (<STRONG>acsc</STRONG>) string capability, and the characters in it may appear on the + screen if the terminal type's database entry incorrectly advertises ACS + support. The name "ACS" originates in the Alternate Character Set + feature of the DEC VT100 terminal. <STRONG>ACS</STRONG> <STRONG>acsc</STRONG> <STRONG>Symbol</STRONG> <STRONG>Default</STRONG> <STRONG>char</STRONG> <STRONG>Glyph</STRONG> <STRONG>Name</STRONG> @@ -172,16 +236,29 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - In <EM>ncurses</EM>, <STRONG>waddch</STRONG> returns <STRONG>ERR</STRONG> if it is not possible to add a complete - character at the cursor position, as when conversion of a multibyte - character to a byte sequence fails, or at least one of the resulting - bytes cannot be added to the window. See section "PORTABILITY" below - regarding the use of <STRONG>waddch</STRONG> with multibyte characters. + In <EM>ncurses</EM>, these functions fail if + + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, + + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, + + <STRONG>o</STRONG> wrapping to a new line is impossible because <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> has not + been called on <EM>win</EM> (or <STRONG>stdscr</STRONG>, as applicable) when a write to its + bottom right location is attempted, or - <STRONG>waddch</STRONG> can successfully write a character at the bottom right location - of the window. However, <EM>ncurses</EM> returns <STRONG>ERR</STRONG> if <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> is not - enabled in that event, because it is not possible to wrap to a new - line. + <STRONG>o</STRONG> it is not possible to add a complete character at the cursor + position. + + The last may be due to different causes: + + <STRONG>o</STRONG> conversion of a wide character to a multibyte character sequence + can fail, or + + <STRONG>o</STRONG> at least one of the bytes resulting from wide character conversion + to a multibyte character sequence cannot be added to the window. + See section "PORTABILITY" below regarding the use of <STRONG>waddch</STRONG> with + wide characters. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. @@ -191,36 +268,92 @@ <STRONG>addch</STRONG>, <STRONG>mvaddch</STRONG>, <STRONG>mvwaddch</STRONG>, and <STRONG>echochar</STRONG> may be implemented as macros. +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + The symbols <EM>ACS</EM><STRONG>_</STRONG><EM>S3</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>S7</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>LEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>GEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>PI</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>NEQUAL</EM>, + and <EM>ACS</EM><STRONG>_</STRONG><EM>STERLING</EM> were not documented in any publicly released System V + and are not standard. However, many publicly available <EM>terminfo</EM> + entries include <STRONG>acs_chars</STRONG> (<STRONG>acsc</STRONG>) capabilities in which their key + characters (<STRONG>pryz{|}</STRONG>) are embedded, and a second-hand list of their + character descriptions has come to light, which identifies them as + VT100 special characters. + + The DEC Special Character and Line Drawing Set (VT100) is indexed by an + ASCII character in the range 96 (`) to 126 (~). That index character + is part of the definition for the curses <STRONG>ACS_</STRONG> symbols. The VT100 + special characters can be categorized in three groups: + + <STRONG>o</STRONG> useful graphic symbols with a standard <STRONG>ACS_</STRONG> symbol, (e.g., the + line-drawing symbols), + + <STRONG>o</STRONG> possibly useful characters (these non-standard symbols), + + <STRONG>o</STRONG> representations of control characters (e.g., newline and vertical + tabulation). + + A few <STRONG>ACS_</STRONG> symbols do not fit into DEC's VT100 scheme. The AT&T + Teletype 5410v1 arrow symbols and <STRONG>ACS_BLOCK</STRONG> use indices outside the + range 96 to 126. Two of the Teletype symbols use indices in that + range, with different meaning versus the VT100: + + <STRONG>o</STRONG> <STRONG>ACS_BOARD</STRONG> corresponds to the VT100 symbol for newline + + <STRONG>o</STRONG> <STRONG>ACS_LANTERN</STRONG> corresponds to the VT100 symbol for vertical tabulation + + AT&T defined <STRONG>ACS_</STRONG> names for the most useful graphic symbols, as well as + for its own. Its header file commented: + + /* + * Standard alternate character set. The current ACS world is + * evolving, so we support only a widely available subset: the + * line drawing characters from the VT100, plus a few from the + * Teletype 5410v1. Eventually there may be support of more + * sophisticated ACS line drawing, such as that in the Teletype + * 5410, the HP line drawing set, and the like. There may be + * support for some non line oriented characters as well. + * + * Line drawing ACS names are of the form ACS_trbl, where t is + * the top, r is the right, b is the bottom, and l is the left. + * t, r, b, and l might be B (blank), S (single), D (double), or + * T (thick). The subset defined here only uses B and S. + */ + + Although these less-useful graphic symbols were not given names, they + were used in <EM>terminfo</EM> entries. The <EM>ncurses</EM> developers invented ACS- + prefixed names for them. + + </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. It specifies no - error conditions for them. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. - SVr4 <EM>curses</EM> describes a successful return value only as "an integer - value other than <STRONG>ERR</STRONG>". + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - The defaults specified for forms-drawing characters apply in the POSIX + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". + + The defaults specified for forms-drawing characters apply in the POSIX locale. </PRE><H3><a name="h3-ACS-Symbols">ACS Symbols</a></H3><PRE> - X/Open Curses states that the <STRONG>ACS_</STRONG> definitions are <EM>char</EM> constants. - + X/Open Curses states that the <EM>ACS</EM><STRONG>_</STRONG> definitions are <EM>char</EM> constants. Some implementations are problematic. - <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, define the ACS symbols as constants; + <STRONG>o</STRONG> Solaris <EM>curses</EM>, for example, defines the ACS symbols as constants; others define them as elements of an array. - This implementation uses an array, <STRONG>acs_map</STRONG>, as did SVr4 <EM>curses</EM>. - NetBSD also uses an array, actually named <STRONG>_acs_char</STRONG>, with a <STRONG>#define</STRONG> - for compatibility. + SVr4 used an array, <EM>acs</EM><STRONG>_</STRONG><EM>map</EM>, as does <EM>ncurses</EM>. NetBSD <EM>curses</EM> also + uses an array, actually named <STRONG>_</STRONG><EM>acs</EM><STRONG>_</STRONG><EM>char</EM>, with a "#define" for + compatibility. - <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <STRONG>ACS_</STRONG> symbols to the analogous - <STRONG>WACS_</STRONG> symbols as if the <STRONG>ACS_</STRONG> symbols were wide characters (see + <STRONG>o</STRONG> HP-UX <EM>curses</EM> equates some of the <EM>ACS</EM><STRONG>_</STRONG> symbols to the analogous + <EM>WACS</EM><STRONG>_</STRONG> symbols as if the <EM>ACS</EM><STRONG>_</STRONG> symbols were wide characters (see <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>). The misdefined symbols are the arrows and others that are not used for line drawing. <STRONG>o</STRONG> X/Open Curses (Issues 2 through 7) has a typographical error for - the <STRONG>ACS_LANTERN</STRONG> symbol, equating its "VT100+ Character" to "I" + the <EM>ACS</EM><STRONG>_</STRONG><EM>LANTERN</EM> symbol, equating its "VT100+ Character" to "I" (capital I), while the header files for SVr4 <EM>curses</EM> and other implementations use "i" (small i). @@ -230,17 +363,9 @@ other hand, its <STRONG>gs6300</STRONG> (AT&T PC6300 with EMOTS Terminal Emulator) description uses lowercase i. - Some ACS symbols (<STRONG>ACS_S3</STRONG>, <STRONG>ACS_S7</STRONG>, <STRONG>ACS_LEQUAL</STRONG>, <STRONG>ACS_GEQUAL</STRONG>, <STRONG>ACS_PI</STRONG>, - <STRONG>ACS_NEQUAL</STRONG>, and <STRONG>ACS_STERLING</STRONG>) were not documented in any publicly - released System V. However, many publicly available <EM>terminfo</EM> entries - include <STRONG>acsc</STRONG> strings in which their key characters <STRONG>(</STRONG>pryz{|}<STRONG>)</STRONG> are - embedded, and a second-hand list of their character descriptions has - come to light. The <EM>ncurses</EM> developers invented ACS-prefixed names for - them. - - The <EM>displayed</EM> values of <STRONG>ACS_</STRONG> constants depend on + The <EM>displayed</EM> values of <EM>ACS</EM><STRONG>_</STRONG> constants depend on - <STRONG>o</STRONG> the <EM>ncurses</EM> ABI--for example, wide-character versus non-wide- + <STRONG>o</STRONG> the <EM>ncurses</EM> ABI -- for example, wide-character versus non-wide- character configurations (the former is capable of displaying Unicode while the latter is not), and @@ -248,59 +373,61 @@ In certain cases, the terminal is unable to display forms-drawing characters <EM>except</EM> by using UTF-8; see the discussion of the - <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM> environment variable in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>). + <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>UTF8</EM><STRONG>_</STRONG><EM>ACS</EM> environment variable in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. </PRE><H3><a name="h3-Character-Set">Character Set</a></H3><PRE> - X/Open Curses assumes that the parameter passed to <STRONG>waddch</STRONG> contains a - single character. As discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, that character may - have been more than eight bits wide in an SVr3 or SVr4 implementation, - but in the X/Open Curses model, the details are not given. The - important distinction between SVr4 <EM>curses</EM> and X/Open Curses is that the - latter separates non-character information (attributes and color) from - the character code, which SVr4 packs into a <EM>chtype</EM> for passage to - <STRONG>waddch</STRONG>. + X/Open Curses assumes that the parameter passed to <EM>waddch</EM> contains a + single character. That character may have been more than eight bits + wide in an SVr3 or SVr4 implementation, but X/Open Curses leaves the + width of a non-wide character code unspecified. The standard further + does not specify the internal structure of a <EM>chtype</EM>, though the use of + bitwise operators to combine the character code with attributes and a + color pair identifier into a <EM>chtype</EM> for passage to <EM>waddch</EM> is common. A + portable application uses only the macros discussed in <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> to + manipulate a <EM>chtype</EM>. - In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character. But the library - allows a multibyte character to be passed in a succession of calls to - <STRONG>waddch</STRONG>. Other implementations do not; a <STRONG>waddch</STRONG> call transmits exactly - one character, which may be rendered in one or more screen locations - depending on whether it is printable. + In <EM>ncurses</EM>, <EM>chtype</EM> holds an eight-bit character, but the library allows + a multibyte character sequence to be passed via a succession of calls + to <EM>waddch</EM>. Other implementations do not; a <EM>waddch</EM> call transmits + exactly one character, which may be rendered in one or more screen + locations depending on whether it is printable (see <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>). + Depending on the locale, <EM>ncurses</EM> inspects the byte passed in each + <EM>waddch</EM> call and checks whether the latest call continues a multibyte + character. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the + character and advances the cursor. If the calling application + interrupts the succession of bytes in a multibyte character sequence by + changing the current location -- for example, with <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> -- <EM>ncurses</EM> + discards the incomplete character. - Depending on the locale settings, <EM>ncurses</EM> inspects the byte passed in - each <STRONG>waddch</STRONG> call, and checks whether the latest call continues a - multibyte sequence. When a character is <EM>complete</EM>, <EM>ncurses</EM> displays the - character and advances the cursor. + For portability to other implementations, do not rely upon the + foregoing behavior. Check whether a character can be represented as a + single byte in the current locale. - If the calling application interrupts the succession of bytes in a - multibyte character sequence by changing the current location--for - example, with <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG>--<EM>ncurses</EM> discards the incomplete character. + <STRONG>o</STRONG> If it can, call either <EM>waddch</EM> or <EM>wadd</EM><STRONG>_</STRONG><EM>wch</EM>. - For portability to other implementations, do not rely upon this - behavior. Check whether a character can be represented as a single - byte in the current locale. + <STRONG>o</STRONG> If it cannot, use only <EM>wadd</EM><STRONG>_</STRONG><EM>wch</EM>. - <STRONG>o</STRONG> If it can, call either <STRONG>waddch</STRONG> or <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>. - <STRONG>o</STRONG> If it cannot, use only <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>. +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced <EM>waddch</EM> and its variants. + SVr3 (1987) added the <EM>echochar</EM> and <EM>wechochar</EM> functions and most of the + <EM>ACS</EM><STRONG>_</STRONG> constants, except for <EM>ACS</EM><STRONG>_</STRONG><EM>GEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>LEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>NEQUAL</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>PI</EM>, + <EM>ACS</EM><STRONG>_</STRONG><EM>S3</EM>, <EM>ACS</EM><STRONG>_</STRONG><EM>S7</EM>, and <EM>ACS</EM><STRONG>_</STRONG><EM>STERLING</EM>. -</PRE><H3><a name="h3-TABSIZE">TABSIZE</a></H3><PRE> - SVr4 and other versions of <EM>curses</EM> implement the <STRONG>TABSIZE</STRONG> variable, but - X/Open Curses does not specify it (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>). + <EM>ncurses</EM> 1.9.6 (1995) furnished the remaining <EM>ACS</EM><STRONG>_</STRONG> constants. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library + <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in its wide-character configuration (<EM>ncursesw</EM>). <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG>, <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, - <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, - <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putchar(3)</STRONG> - - + <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, + <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putchar(3)</STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -308,20 +435,21 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF= <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a> <ul> -<li><a href="#h3-Adding-Characters">Adding Characters</a></li> -<li><a href="#h3-Echoing-Characters">Echoing Characters</a></li> +<li><a href="#h3-waddch">waddch</a></li> +<li><a href="#h3-wechochar">wechochar</a></li> <li><a href="#h3-Forms-Drawing-Characters">Forms-Drawing Characters</a></li> </ul> </li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a> <ul> <li><a href="#h3-ACS-Symbols">ACS Symbols</a></li> <li><a href="#h3-Character-Set">Character Set</a></li> -<li><a href="#h3-TABSIZE">TABSIZE</a></li> </ul> </li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_addchstr.3x.html b/doc/html/man/curs_addchstr.3x.html index a3441e6c9a1d..8aa40802eaf1 100644 --- a/doc/html/man/curs_addchstr.3x.html +++ b/doc/html/man/curs_addchstr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 1998-2012,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,86 +27,95 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_addchstr.3x,v 1.45 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_addchstr.3x,v 1.64 2025/08/16 19:56:13 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_addchstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_addchstr 3x 2025-08-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_addchstr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_addchstr 3x 2025-08-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>addchstr</STRONG>, <STRONG>addchnstr</STRONG>, <STRONG>waddchstr</STRONG>, <STRONG>waddchnstr</STRONG>, <STRONG>mvaddchstr</STRONG>, <STRONG>mvaddchnstr</STRONG>, - <STRONG>mvwaddchstr</STRONG>, <STRONG>mvwaddchnstr</STRONG> - add a <EM>curses</EM> character string to a window + <STRONG>addchstr</STRONG>, <STRONG>waddchstr</STRONG>, <STRONG>mvaddchstr</STRONG>, <STRONG>mvwaddchstr</STRONG>, <STRONG>addchnstr</STRONG>, <STRONG>waddchnstr</STRONG>, + <STRONG>mvaddchnstr</STRONG>, <STRONG>mvwaddchnstr</STRONG> - add a <EM>curses</EM> character string to a window </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>addchstr(const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>waddchstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvaddchstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwaddchstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>addchstr(const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>waddchstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvaddchstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwaddchstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>addchnstr(const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>waddchnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvaddchnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwaddchnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>addchnstr(const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>waddchnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvaddchnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwaddchnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These functions copy the (null-terminated) <EM>chstr</EM> array into the window - image structure starting at the current cursor position. - - The four functions with <EM>n</EM> as the last argument copy at most <EM>n</EM> elements, - but no more than will fit on the line. If <STRONG>n</STRONG>=<STRONG>-1</STRONG> then the whole array is - copied, to the maximum number of characters that will fit on the line. + <STRONG>waddchstr</STRONG> copies the string of <EM>curses</EM> characters <EM>chstr</EM> to the window + <EM>win</EM>. A null <EM>curses</EM> character terminates the string. <STRONG>waddchnstr</STRONG> does + the same, but copies at most <EM>n</EM> characters, or as many as possible if <EM>n</EM> + is <STRONG>-1</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions. - The window cursor is <EM>not</EM> advanced. These functions are faster than - <STRONG>waddnstr</STRONG>. On the other hand: + Because these functions do not call <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> internally, they are + faster than <STRONG><A HREF="curs_addstr.3x.html">waddstr(3x)</A></STRONG> and <STRONG><A HREF="curs_addstr.3x.html">waddnstr(3x)</A></STRONG>. On the other hand, they - <STRONG>o</STRONG> they do not perform checking (such as for the newline, backspace, - or carriage return characters), + <STRONG>o</STRONG> do not treat the backspace, carriage return, or line feed + characters specially; - <STRONG>o</STRONG> they do not advance the current cursor position, + <STRONG>o</STRONG> do not represent unprintable characters with <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>; - <STRONG>o</STRONG> they do not expand other control characters to ^-escapes, and + <STRONG>o</STRONG> do not update the cursor position to follow the last character + written; and - <STRONG>o</STRONG> they truncate the string if it crosses the right margin, rather - than wrapping it around to the new line. + <STRONG>o</STRONG> truncate the string at the window's right margin, rather than + wrapping it to the next line and potentially scrolling. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All functions return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - X/Open Curses does not specify any error conditions. This - implementation returns an error + In <EM>ncurses</EM>, these functions fail if - <STRONG>o</STRONG> if the <EM>win</EM> parameter is null or + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> if the <EM>wchstr</EM> parameter is null. + <STRONG>o</STRONG> <EM>chstr</EM> is a null pointer, or - Functions prefixed with "mv" first perform cursor movement and fail if + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer. + + Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All functions except <STRONG>waddchnstr</STRONG> may be macros. + All of these functions except <STRONG>waddchnstr</STRONG> may be implemented as macros. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr3.1 (1987) introduced these functions. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> @@ -115,9 +124,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG> +ncurses 6.6 2025-08-16 <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -127,6 +134,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="cu <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_addstr.3x.html b/doc/html/man/curs_addstr.3x.html index b7f1c689b994..27c03f0e6366 100644 --- a/doc/html/man/curs_addstr.3x.html +++ b/doc/html/man/curs_addstr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 1998-2012,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,78 +27,86 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_addstr.3x,v 1.45 2024/04/20 19:18:18 tom Exp @ + * @Id: curs_addstr.3x,v 1.71 2025/10/21 00:09:34 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_addstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_addstr 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_addstr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_addstr 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>addstr</STRONG>, <STRONG>addnstr</STRONG>, <STRONG>waddstr</STRONG>, <STRONG>waddnstr</STRONG>, <STRONG>mvaddstr</STRONG>, <STRONG>mvaddnstr</STRONG>, <STRONG>mvwaddstr</STRONG>, + <STRONG>addstr</STRONG>, <STRONG>waddstr</STRONG>, <STRONG>mvaddstr</STRONG>, <STRONG>mvwaddstr</STRONG>, <STRONG>addnstr</STRONG>, <STRONG>waddnstr</STRONG>, <STRONG>mvaddnstr</STRONG>, <STRONG>mvwaddnstr</STRONG> - add a string to a <EM>curses</EM> window and advance the cursor </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>addstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvaddstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwaddstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>waddstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>addstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>waddstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvaddstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwaddstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>addnstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvaddnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwaddnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>waddnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>addnstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>waddnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvaddnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwaddnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> <STRONG>waddstr</STRONG> writes the characters of the (null-terminated) string <EM>str</EM> to - the window <EM>win</EM>. Its process is similar to calling <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> for each - <EM>char</EM> in <EM>str</EM>. Control characters are processed as in <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG>. - - <STRONG>waddnstr</STRONG> writes at most <EM>n</EM> characters, or until a terminating null - character occurs in <EM>str</EM>. If <EM>n</EM> is -1, <STRONG>waddnstr</STRONG> writes the entire - string. - - <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions. + the window <EM>win</EM>, as if by calling <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> for each <EM>char</EM> in <EM>str</EM>. + <STRONG>waddnstr</STRONG> is similar, but writes at most <EM>n</EM> characters. If <EM>n</EM> is -1, + <STRONG>waddnstr</STRONG> writes the entire string. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants + of these functions. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - X/Open Curses does not specify any error conditions. <EM>ncurses</EM> returns - an error + In <EM>ncurses</EM>, these functions fail if + + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> if the window pointer is <STRONG>NULL</STRONG>, + <STRONG>o</STRONG> <EM>str</EM> is a null pointer, - <STRONG>o</STRONG> if the string pointer is <STRONG>NULL</STRONG>, or + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, or - <STRONG>o</STRONG> if an internal <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> call returns an error. + <STRONG>o</STRONG> an internal <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> call returns <STRONG>ERR</STRONG>. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All of these functions except <STRONG>waddnstr</STRONG> may be macros. + All of these functions except <STRONG>waddnstr</STRONG> may be implemented as macros. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced <EM>waddstr</EM> along with its variants, the latter + defined as macros. + + SVr3.1 (1987) added <EM>waddnstr</EM> (and its variants) redefining <EM>waddstr</EM> as a + macro wrapping it. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> @@ -107,9 +115,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_addchstr.3x.html">curs_addchstr(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -119,6 +125,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF=" <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_addwstr.3x.html b/doc/html/man/curs_addwstr.3x.html index ce3229acc228..8fe360b8e955 100644 --- a/doc/html/man/curs_addwstr.3x.html +++ b/doc/html/man/curs_addwstr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 2002-2012,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,74 +27,68 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_addwstr.3x,v 1.37 2024/04/20 19:18:18 tom Exp @ + * @Id: curs_addwstr.3x,v 1.60 2025/03/15 20:41:04 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_addwstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_addwstr 3x 2025-03-15 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_addwstr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_addwstr 3x 2025-03-15 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>addwstr</STRONG>, <STRONG>addnwstr</STRONG>, <STRONG>waddwstr</STRONG>, <STRONG>waddnwstr</STRONG>, <STRONG>mvaddwstr</STRONG>, <STRONG>mvaddnwstr</STRONG>, - <STRONG>mvwaddwstr</STRONG>, <STRONG>mvwaddnwstr</STRONG> - add a wide-character string to a <EM>curses</EM> + <STRONG>addwstr</STRONG>, <STRONG>waddwstr</STRONG>, <STRONG>mvaddwstr</STRONG>, <STRONG>mvwaddwstr</STRONG>, <STRONG>addnwstr</STRONG>, <STRONG>waddnwstr</STRONG>, + <STRONG>mvaddnwstr</STRONG>, <STRONG>mvwaddnwstr</STRONG> - add a wide-character string to a <EM>curses</EM> window and advance the cursor </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>addwstr(const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvaddwstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwaddwstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>waddwstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>addwstr(const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>waddwstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvaddwstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwaddwstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>addnwstr(const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvaddnwstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwaddnwstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>waddnwstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>addnwstr(const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>waddnwstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvaddnwstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwaddnwstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> <STRONG>waddwstr</STRONG> writes the characters of the (wide-null-terminated) wide- - character string <EM>wstr</EM> to the window <EM>win</EM>. Its process is similar to - constructing a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> for each <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> in <EM>wstr</EM>, then calling - <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> with the resulting <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. - - <STRONG>o</STRONG> Spacing and non-spacing characters in the string are processed one - at a time, and - - <STRONG>o</STRONG> control characters are processed as in <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>. - - <STRONG>waddnwstr</STRONG> writes at most <EM>n</EM> wide characters, or until a terminating wide - null character occurs in <EM>wstr</EM>. If <EM>n</EM> is -1, <STRONG>waddnwstr</STRONG> writes the entire - wide string. - + character string <EM>wstr</EM> to the window <EM>win</EM>, as if by constructing a + <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> for each <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> in <EM>wstr</EM>, then calling <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> with the + resulting <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. <EM>curses</EM> processes spacing and non-spacing characters + in <EM>wstr</EM> one at a time. <STRONG>waddnwstr</STRONG> is similar, but writes at most <EM>n</EM> wide + characters. If <EM>n</EM> is -1, <STRONG>waddnwstr</STRONG> writes the entire wide string. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - X/Open Curses does not specify any error conditions. <EM>ncurses</EM> returns - an error + In <EM>ncurses</EM>, these functions fail if - <STRONG>o</STRONG> if the window pointer is <STRONG>NULL</STRONG>, + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> if the string pointer is <STRONG>NULL</STRONG>, or + <STRONG>o</STRONG> <EM>wstr</EM> is a null pointer, - <STRONG>o</STRONG> if an internal <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> call returns an error. + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, or + + <STRONG>o</STRONG> an internal <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> call returns <STRONG>ERR</STRONG>. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. @@ -105,18 +99,26 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. + X/Open Curses Issue 4 describes these functions. + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + X/Open Curses Issue 4 (1995) initially specified these functions. The + System V Interface Definition Version 4 of the same year specified + functions named <EM>waddwstr</EM> and <EM>waddnwstr</EM> (and the usual variants). These + were later additions to SVr4.<EM>x</EM>, not appearing in the first SVr4 (1989). </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library + <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in its non-wide-character configuration. <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wchstr.3x.html">curs_add_wchstr(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG> +ncurses 6.6 2025-03-15 <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -126,6 +128,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="c <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_attr.3x.html b/doc/html/man/curs_attr.3x.html index bc1fd859d06a..640e8664a0fd 100644 --- a/doc/html/man/curs_attr.3x.html +++ b/doc/html/man/curs_attr.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_attr.3x,v 1.105 2024/04/27 17:54:42 tom Exp @ + * @Id: curs_attr.3x,v 1.142 2025/11/12 01:05:49 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_attr 3x 2024-04-27 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_attr 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_attr 3x 2024-04-27 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_attr 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>attr_get</STRONG>, <STRONG>wattr_get</STRONG>, <STRONG>attr_set</STRONG>, <STRONG>wattr_set</STRONG>, <STRONG>attr_off</STRONG>, <STRONG>wattr_off</STRONG>, <STRONG>attr_on</STRONG>, <STRONG>wattr_on</STRONG>, <STRONG>attroff</STRONG>, <STRONG>wattroff</STRONG>, <STRONG>attron</STRONG>, <STRONG>wattron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>wattrset</STRONG>, <STRONG>chgat</STRONG>, @@ -121,24 +119,25 @@ Use <STRONG>wattr_get</STRONG> to retrieve attributes for the given window. Use <STRONG>attr_on</STRONG> and <STRONG>wattr_on</STRONG> to turn on window attributes, i.e., values - OR'd together in <EM>attr</EM>, without affecting other attributes. Use - <STRONG>attr_off</STRONG> and <STRONG>wattr_off</STRONG> to turn off window attributes, again values OR'd - together in <EM>attr</EM>, without affecting other attributes. + logically "or"-ed together in <EM>attr</EM>, without affecting other attributes. + Use <STRONG>attr_off</STRONG> and <STRONG>wattr_off</STRONG> to turn off window attributes, again values + logically "or"-ed together in <EM>attr</EM>, without affecting other attributes. </PRE><H3><a name="h3-Legacy-Window-Attributes">Legacy Window Attributes</a></H3><PRE> - The X/Open window attribute routines which <EM>set</EM> or <EM>get</EM>, turn <EM>on</EM> or <EM>off</EM> - are extensions of older routines which assume that color pairs are OR'd - into the attribute parameter. These newer routines use similar names, - because X/Open simply added an underscore (<STRONG>_</STRONG>) for the newer names. - - The <STRONG>int</STRONG> datatype used in the legacy routines is treated as if it is the - same size as <STRONG>chtype</STRONG> (used by <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>). It holds the common video - attributes (such as bold, reverse), as well as a few bits for color. - Those bits correspond to the <STRONG>A_COLOR</STRONG> symbol. The <STRONG>COLOR_PAIR</STRONG> macro - provides a value which can be OR'd into the attribute parameter. For - example, as long as that value fits into the <STRONG>A_COLOR</STRONG> mask, then these - calls produce similar results: + The X/Open window attribute routines which <EM>set</EM> or <EM>get</EM>, turn <EM>on</EM> or <EM>off</EM> + are extensions of older routines which assume that color pairs are + logically "or"-ed into the attribute parameter. These newer routines + use similar names, because X/Open simply added an underscore (<STRONG>_</STRONG>) for + the newer names. + + The <EM>int</EM> datatype used in the legacy routines is treated as if it is the + same size as <EM>chtype</EM> (used by <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>). It holds the common video + attributes (such as bold, reverse), as well as a few bits for color. + Those bits correspond to the <STRONG>A_COLOR</STRONG> symbol. The <STRONG>COLOR_PAIR</STRONG> macro + provides a value which can be logically "or"-ed into the attribute + parameter. For example, as long as that value fits into the <STRONG>A_COLOR</STRONG> + mask, then these calls produce similar results: attrset(A_BOLD | COLOR_PAIR(<EM>pair</EM>)); attr_set(A_BOLD, <EM>pair</EM>, NULL); @@ -148,28 +147,28 @@ (8) bits, then <STRONG>COLOR_PAIR(</STRONG><EM>259</EM><STRONG>)</STRONG> is 4 (i.e., 259 is 4 more than the limit 255). - The <STRONG>PAIR_NUMBER</STRONG> macro extracts a pair number from an <STRONG>int</STRONG> (or <STRONG>chtype</STRONG>). - For example, the <EM>input</EM> and <EM>output</EM> values in these statements would be + The <STRONG>PAIR_NUMBER</STRONG> macro extracts a pair number from an <EM>int</EM> (or <EM>chtype</EM>). + For example, the <EM>input</EM> and <EM>output</EM> values in these statements would be the same: int value = A_BOLD | COLOR_PAIR(<EM>input</EM>); int <EM>output</EM> = PAIR_NUMBER(value); - The <STRONG>attrset</STRONG> routine is a legacy feature predating SVr4 curses but kept - in X/Open Curses for the same reason that SVr4 curses kept it: + The <STRONG>attrset</STRONG> routine is a legacy feature predating SVr4 <EM>curses</EM> but kept + in X/Open Curses for the same reason that SVr4 <EM>curses</EM> kept it: compatibility. - The remaining <STRONG>attr</STRONG>* functions operate exactly like the corresponding - <STRONG>attr_</STRONG>* functions, except that they take arguments of type <STRONG>int</STRONG> rather - than <STRONG>attr_t</STRONG>. + The remaining <STRONG>attr</STRONG>* functions operate exactly like the corresponding + <STRONG>attr_</STRONG>* functions, except that they take arguments of type <EM>int</EM> rather + than <EM>attr</EM><STRONG>_</STRONG><EM>t</EM>. - There is no corresponding <STRONG>attrget</STRONG> function as such in X/Open Curses, + There is no corresponding <STRONG>attrget</STRONG> function as such in X/Open Curses, although <EM>ncurses</EM> provides <STRONG>getattrs</STRONG> (see <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>). </PRE><H3><a name="h3-Change-Character-Rendition">Change Character Rendition</a></H3><PRE> The routine <STRONG>chgat</STRONG> changes the attributes of a given number of - characters starting at the current cursor location of <STRONG>stdscr</STRONG>. It does + characters starting at the current cursor location of <STRONG>stdscr</STRONG>. It does not update the cursor and does not perform wrapping. A character count of -1 or greater than the remaining window width means to change attributes all the way to the end of the current line. The <STRONG>wchgat</STRONG> @@ -182,32 +181,32 @@ </PRE><H3><a name="h3-Change-Window-Color">Change Window Color</a></H3><PRE> The routine <STRONG>color_set</STRONG> sets the current color of the given window to the - foreground/background combination described by the color <EM>pair</EM> + foreground/background combination described by the color <EM>pair</EM> parameter. </PRE><H3><a name="h3-Standout">Standout</a></H3><PRE> - The routine <STRONG>standout</STRONG> is the same as <STRONG>attron(A_STANDOUT)</STRONG>. The routine - <STRONG>standend</STRONG> is the same as <STRONG>attrset(A_NORMAL)</STRONG> or <STRONG>attrset(0)</STRONG>, that is, it + The routine <STRONG>standout</STRONG> is the same as <STRONG>attron(A_STANDOUT)</STRONG>. The routine + <STRONG>standend</STRONG> is the same as <STRONG>attrset(A_NORMAL)</STRONG> or <STRONG>attrset(0)</STRONG>, that is, it turns off all attributes. X/Open Curses does not mark these "restricted", because <STRONG>o</STRONG> they have well established legacy use, and - <STRONG>o</STRONG> there is no ambiguity about the way the attributes might be + <STRONG>o</STRONG> there is no ambiguity about the way the attributes might be combined with a color pair. </PRE><H3><a name="h3-Video-Attributes">Video Attributes</a></H3><PRE> - The following video attributes, defined in <STRONG><curses.h></STRONG>, can be passed to - the routines <STRONG>attron</STRONG>, <STRONG>attroff</STRONG>, and <STRONG>attrset</STRONG>, or OR'd with the characters - passed to <STRONG>addch</STRONG> (see <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>). + The following video attributes, defined in <EM>curses.h</EM>, can be passed to + <STRONG>attron</STRONG>, <STRONG>attroff</STRONG>, <STRONG>attrset</STRONG>, and logically "or"-ed with characters passed + to <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>. <STRONG>Name</STRONG> <STRONG>Description</STRONG> ----------------------------------------------------------------- <STRONG>A_NORMAL</STRONG> Normal display (no highlight) - <STRONG>A_STANDOUT</STRONG> Best highlighting mode of the terminal + <STRONG>A_STANDOUT</STRONG> Best highlighting mode available <STRONG>A_UNDERLINE</STRONG> Underlining <STRONG>A_REVERSE</STRONG> Reverse video <STRONG>A_BLINK</STRONG> Blinking @@ -217,11 +216,12 @@ <STRONG>A_INVIS</STRONG> Invisible or blank mode <STRONG>A_ALTCHARSET</STRONG> Alternate character set <STRONG>A_ITALIC</STRONG> Italics (non-X/Open extension) - <STRONG>A_CHARTEXT</STRONG> Bit-mask to extract a character - <STRONG>A_COLOR</STRONG> Bit-mask to extract a color (legacy routines) + <STRONG>A_ATTRIBUTES</STRONG> Mask to extract character code + <STRONG>A_CHARTEXT</STRONG> Mask to extract attributes + <STRONG>A_COLOR</STRONG> Mask to extract color pair identifier - These video attributes are supported by <STRONG>attr_on</STRONG> and related functions - (which also support the attributes recognized by <STRONG>attron</STRONG>, etc.): + <STRONG>attr_on</STRONG>, <STRONG>attr_off</STRONG>, and <STRONG>attr_set</STRONG> support the foregoing as well as the + following additional attributes. <STRONG>Name</STRONG> <STRONG>Description</STRONG> ----------------------------------------------------------------- @@ -232,42 +232,33 @@ <STRONG>WA_TOP</STRONG> Top highlight <STRONG>WA_VERTICAL</STRONG> Vertical highlight - The return values of many of these routines are not meaningful (they - are implemented as macro-expanded assignments and simply return their - argument). The SVr4 manual page claims (falsely) that these routines - always return <STRONG>1</STRONG>. - </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All routines return the integer <STRONG>OK</STRONG> on success, or <STRONG>ERR</STRONG> on failure. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - X/Open Curses does not specify any error conditions. + In <EM>ncurses</EM>, they return <STRONG>ERR</STRONG> if <EM>win</EM> is <EM>NULL</EM>. - This implementation + <STRONG>wcolor_set</STRONG> returns <STRONG>ERR</STRONG> if <EM>pair</EM> is outside the range <STRONG>0</STRONG>..<STRONG>COLOR_PAIRS-1</STRONG>. - <STRONG>o</STRONG> returns an error if the window pointer is null. - - <STRONG>o</STRONG> returns an error if the color pair parameter for <STRONG>wcolor_set</STRONG> is - outside the range 0..COLOR_PAIRS-1. - - <STRONG>o</STRONG> does not return an error if either of the parameters of <STRONG>wattr_get</STRONG> - used for retrieving attribute or color pair values is <STRONG>NULL</STRONG>. + <STRONG>wattr_get</STRONG> does <EM>not</EM> fail if its <EM>attrs</EM> or <EM>pair</EM> parameter is <EM>NULL</EM>. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - These functions may be macros: + <STRONG>attr_on</STRONG>, <STRONG>attr_off</STRONG>, <STRONG>attr_set</STRONG>, <STRONG>wattr_set</STRONG>, <STRONG>chgat</STRONG>, <STRONG>mvchgat</STRONG>, <STRONG>mvwchgat</STRONG>, + <STRONG>wchgat</STRONG>, and <STRONG>color_set</STRONG> are part of <EM>ncurses</EM>'s wide-character API, and are + not available in its non-wide-character configuration. - <STRONG>attroff</STRONG>, <STRONG>wattroff</STRONG>, <STRONG>attron</STRONG>, <STRONG>wattron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>wattrset</STRONG>, <STRONG>standend</STRONG> - and <STRONG>standout</STRONG>. + <STRONG>attron</STRONG>, <STRONG>wattron</STRONG>, <STRONG>attroff</STRONG>, <STRONG>wattroff</STRONG>, <STRONG>attrset</STRONG>, <STRONG>wattrset</STRONG>, <STRONG>standout</STRONG>, and + <STRONG>standend</STRONG> may be implemented as macros. - Color pair values can only be OR'd with attributes if the pair number - is less than 256. The alternate functions such as <STRONG>color_set</STRONG> can pass a - color pair value directly. However, <EM>ncurses</EM> ABI 4 and 5 simply OR this - value within the alternate functions. You must use <EM>ncurses</EM> ABI 6 to - support more than 256 color pairs. + Color pair values may be logically "or"-ed with attributes if the pair + number is less than 256. The alternate functions such as <STRONG>color_set</STRONG> can + pass a color pair value directly. However, <EM>ncurses</EM> ABI 4 and 5 simply + logically "or" this value within the alternate functions. You must use + <EM>ncurses</EM> ABI 6 to support more than 256 color pairs. </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> @@ -280,28 +271,33 @@ Each of the functions added by XSI Curses has a parameter <EM>opts</EM>, which X/Open Curses still (after more than twenty years) documents as - reserved for future use, saying that it should be <STRONG>NULL</STRONG>. This + reserved for future use, saying that it should be <EM>NULL</EM>. This implementation uses that parameter in ABI 6 for the functions which have a color pair parameter to support <EM>extended</EM> <EM>color</EM> <EM>pairs</EM>: <STRONG>o</STRONG> For functions which modify the color, e.g., <STRONG>wattr_set</STRONG> and <STRONG>wattr_on</STRONG>, - if <EM>opts</EM> is set it is treated as a pointer to <STRONG>int</STRONG>, and used to set - the color pair instead of the <STRONG>short</STRONG> <EM>pair</EM> parameter. + if <EM>opts</EM> is set it is treated as a pointer to <EM>int</EM>, and used to set + the color pair instead of the <EM>short</EM> <EM>pair</EM> parameter. <STRONG>o</STRONG> For functions which retrieve the color, e.g., <STRONG>wattr_get</STRONG>, if <EM>opts</EM> is - set it is treated as a pointer to <STRONG>int</STRONG>, and used to retrieve the - color pair as an <STRONG>int</STRONG> value, in addition to retrieving it via the - standard pointer to <STRONG>short</STRONG> parameter. + set it is treated as a pointer to <EM>int</EM>, and used to retrieve the + color pair as an <EM>int</EM> value, in addition to retrieving it via the + standard pointer to <EM>short</EM> parameter. <STRONG>o</STRONG> For functions which turn attributes off, e.g., <STRONG>wattr_off</STRONG>, the <EM>opts</EM> - parameter is ignored except except to check that it is <STRONG>NULL</STRONG>. + parameter is ignored except to check that it is <EM>NULL</EM>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. The standard - defined the dedicated type for highlights, <STRONG>attr_t</STRONG>, which was not - defined in SVr4 curses. The functions taking <STRONG>attr_t</STRONG> arguments were not - supported under SVr4. + These functions are described in X/Open Curses Issue 4. It specifies + no error conditions for them. + + The standard defined the dedicated type for highlights, <EM>attr</EM><STRONG>_</STRONG><EM>t</EM>, which + was not defined in SVr4 <EM>curses</EM>. The functions taking <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> arguments + were not supported under SVr4. + + SVr4 describes the functions not taking <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> or <EM>pair</EM> arguments as + always returning <STRONG>1</STRONG>. Very old versions of this library did not force an update of the screen when changing the attributes. Use <STRONG>touchwin</STRONG> to force the screen to @@ -310,7 +306,7 @@ X/Open Curses states that whether the traditional functions <STRONG>attron</STRONG>/<STRONG>attroff</STRONG>/<STRONG>attrset</STRONG> can manipulate attributes other than <STRONG>A_BLINK</STRONG>, <STRONG>A_BOLD</STRONG>, <STRONG>A_DIM</STRONG>, <STRONG>A_REVERSE</STRONG>, <STRONG>A_STANDOUT</STRONG>, or <STRONG>A_UNDERLINE</STRONG> is "unspecified". - Under this implementation as well as SVr4 curses, these functions + Under this implementation as well as SVr4 <EM>curses</EM>, these functions correctly manipulate all other highlights (specifically, <STRONG>A_ALTCHARSET</STRONG>, <STRONG>A_PROTECT</STRONG>, and <STRONG>A_INVIS</STRONG>). @@ -324,102 +320,99 @@ the newer set of names: <STRONG>Name</STRONG> <STRONG>Description</STRONG> - ----------------------------------------------------------------- + ------------------------------------------------- <STRONG>WA_NORMAL</STRONG> Normal display (no highlight) - <STRONG>WA_STANDOUT</STRONG> Best highlighting mode of the terminal + <STRONG>WA_STANDOUT</STRONG> Best highlighting mode available <STRONG>WA_UNDERLINE</STRONG> Underlining <STRONG>WA_REVERSE</STRONG> Reverse video <STRONG>WA_BLINK</STRONG> Blinking <STRONG>WA_DIM</STRONG> Half bright <STRONG>WA_BOLD</STRONG> Extra bright or bold - <STRONG>WA_ALTCHARSET</STRONG> Alternate character set - X/Open Curses does not assign values to these symbols, nor does it - state whether or not they are related to the similarly-named A_NORMAL, + X/Open Curses does not assign values to these symbols, nor does it + state whether or not they are related to the similarly-named A_NORMAL, etc.: - <STRONG>o</STRONG> X/Open Curses specifies that each pair of corresponding <STRONG>A_</STRONG> and - <STRONG>WA_</STRONG>-using functions operates on the same current-highlight + <STRONG>o</STRONG> X/Open Curses specifies that each pair of corresponding <STRONG>A_</STRONG> and + <STRONG>WA_</STRONG>-using functions operates on the same current-highlight information. - <STRONG>o</STRONG> However, in some implementations, those symbols have unrelated + <STRONG>o</STRONG> However, in some implementations, those symbols have unrelated values. - For example, the Solaris <EM>xpg4</EM> (X/Open) curses declares <STRONG>attr_t</STRONG> to be - an unsigned short integer (16-bits), while <STRONG>chtype</STRONG> is a unsigned + For example, the Solaris <EM>xpg4</EM> (X/Open) <EM>curses</EM> declares <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> to be + an unsigned short integer (16-bits), while <EM>chtype</EM> is a unsigned integer (32-bits). The <STRONG>WA_</STRONG> symbols in this case are different from - the <STRONG>A_</STRONG> symbols because they are used for a smaller datatype which + the <STRONG>A_</STRONG> symbols because they are used for a smaller datatype which does not represent <STRONG>A_CHARTEXT</STRONG> or <STRONG>A_COLOR</STRONG>. In this implementation (as in many others), the values happen to be - the same because it simplifies copying information between <STRONG>chtype</STRONG> - and <STRONG>cchar_t</STRONG> variables. + the same because it simplifies copying information between <EM>chtype</EM> + and <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> variables. - <STRONG>o</STRONG> Because <EM>ncurses</EM>'s <STRONG>attr_t</STRONG> can hold a color pair (in the <STRONG>A_COLOR</STRONG> + <STRONG>o</STRONG> Because <EM>ncurses</EM>'s <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> can hold a color pair (in the <STRONG>A_COLOR</STRONG> field), a call to <STRONG>wattr_on</STRONG>, <STRONG>wattr_off</STRONG>, or <STRONG>wattr_set</STRONG> may alter the window's color. If the color pair information in the attribute parameter is zero, no change is made to the window's color. - This is consistent with SVr4 curses; X/Open Curses does not specify + This is consistent with SVr4 <EM>curses</EM>; X/Open Curses does not specify this. - The X/Open Curses extended conformance level adds new highlights - <STRONG>A_HORIZONTAL</STRONG>, <STRONG>A_LEFT</STRONG>, <STRONG>A_LOW</STRONG>, <STRONG>A_RIGHT</STRONG>, <STRONG>A_TOP</STRONG>, <STRONG>A_VERTICAL</STRONG> (and - corresponding <STRONG>WA_</STRONG> macros for each). As of August 2013, no known + The X/Open Curses extended conformance level adds new highlights + <STRONG>A_HORIZONTAL</STRONG>, <STRONG>A_LEFT</STRONG>, <STRONG>A_LOW</STRONG>, <STRONG>A_RIGHT</STRONG>, <STRONG>A_TOP</STRONG>, <STRONG>A_VERTICAL</STRONG> (and + corresponding <STRONG>WA_</STRONG> macros for each). As of August 2013, no known terminal provides these highlights (i.e., via the <STRONG>sgr1</STRONG> capability). </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - X/Open Curses is largely based on SVr4 curses, adding support for - "wide-characters" (not specific to Unicode). Some of the X/Open - differences from SVr4 curses address the way video attributes can be - applied to wide-characters. But aside from that, <STRONG>attrset</STRONG> and <STRONG>attr_set</STRONG> - are similar. SVr4 curses provided the basic features for manipulating - video attributes. However, earlier versions of curses provided a part - of these features. - - As seen in 2.8BSD, curses assumed 7-bit characters, using the eighth - bit of a byte to represent the <EM>standout</EM> feature (often implemented as - bold and/or reverse video). The BSD curses library provided functions - <STRONG>standout</STRONG> and <STRONG>standend</STRONG> which were carried along into X/Open Curses due - to their pervasive use in legacy applications. - - Some terminals in the 1980s could support a variety of video - attributes, although the BSD curses library could do nothing with - those. System V (1983) provided an improved curses library. It - defined the <STRONG>A_</STRONG> symbols for use by applications to manipulate the other - attributes. There are few useful references for the chronology. - - Goodheart's book <EM>UNIX</EM> <EM>Curses</EM> <EM>Explained</EM> (1991) describes SVr3 (1987), - commenting on several functions: - - <STRONG>o</STRONG> the <STRONG>attron</STRONG>, <STRONG>attroff</STRONG>, <STRONG>attrset</STRONG> functions (and most of the functions - found in SVr4 but not in BSD curses) were introduced by System V, - - <STRONG>o</STRONG> the alternate character set feature with <STRONG>A_ALTCHARSET</STRONG> was added in - SVr2 and improved in SVr3 (by adding <STRONG>acs_map[]</STRONG>), - - <STRONG>o</STRONG> <STRONG>start_color</STRONG> and related color-functions were introduced by System - V.3.2, - - <STRONG>o</STRONG> pads, soft-keys were added in SVr3, and - - Goodheart did not mention the background character or the <STRONG>cchar_t</STRONG> type. - Those are respectively SVr4 and X/Open features. He did mention the <STRONG>A_</STRONG> - constants, but did not indicate their values. Those were not the same - in different systems, even for those marked as System V. - - Different Unix systems used different sizes for the bit-fields in - <STRONG>chtype</STRONG> for <EM>characters</EM> and <EM>colors</EM>, and took into account the different - integer sizes (32-bit versus 64-bit). - - This table showing the number of bits for <STRONG>A_COLOR</STRONG> and <STRONG>A_CHARTEXT</STRONG> was - gleaned from the curses header files for various operating systems and - architectures. The inferred architecture and notes reflect the format - and size of the defined constants as well as clues such as the - alternate character set implementation. A 32-bit library can be used - on a 64-bit system, but not necessarily the reverse. + 4BSD (1980) used a <EM>char</EM> to represent each cell of the terminal screen. + It assumed 7-bit character codes, employing the eighth bit of a byte to + represent a <EM>standout</EM> attribute (often implemented as bold and/or + reverse video). It introduced <EM>standout</EM>, <EM>standend</EM>, <EM>wstandout</EM>, and + <EM>wstandend</EM> functions to manipulate this bit. Despite their + inflexibility, they carried over into System V <EM>curses</EM> and ultimately + X/Open Curses due to their pervasive use in legacy applications. While + some 1980s terminals supported a variety of video attributes, BSD + <EM>curses</EM> could do nothing with them. + + SVr2 (1984) provided an improved <EM>curses</EM> library, introducing <EM>chtype</EM> to + create the abstract notion of a <EM>curses</EM> character; this was by default + an <EM>unsigned</EM> <EM>short</EM>, with a provision for compile-time redefinition to + other integral types (a freedom not necessarily available to users of + shared libraries, and in any event a source license was necessary to + exercise it). It added the functions <EM>attron</EM>, <EM>attroff</EM>, <EM>attrset</EM>, + <EM>wattron</EM>, <EM>wattroff</EM>, and <EM>wattrset</EM>, and defined the <EM>A</EM><STRONG>_</STRONG> macros listed above + (except for <EM>A</EM><STRONG>_</STRONG><EM>ITALIC</EM> and <EM>A</EM><STRONG>_</STRONG><EM>COLOR</EM>) for use by applications to manipulate + other attributes. The values of these macros were not necessarily the + same in different systems, even among those certified as System V. + + SVr3.2 (1988) added the <EM>A</EM><STRONG>_</STRONG><EM>COLOR</EM> macro along with a color system; see + <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>. + + X/Open Curses Issue 4 (1995) is largely based on SVr4 <EM>curses</EM>, but + recognized that the <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> type of ISO C95 was intended to house only + a single character code, not a sequence of codes combining with a base + character, let alone could it reliably offer room for a color pair + identifier and a set of attribute bits with a potential for further + growth -- thus the standard invented the <EM>curses</EM> complex character type + <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> and a separate type <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> for storage of attribute bits. The + new types brought along several new functions to manipulate them, some + corresponding to existing <EM>chtype</EM>-based functions (<EM>attr</EM><STRONG>_</STRONG><EM>on</EM>, <EM>attr</EM><STRONG>_</STRONG><EM>off</EM>, + <EM>attr</EM><STRONG>_</STRONG><EM>set</EM>, <EM>wattr</EM><STRONG>_</STRONG><EM>on</EM>, <EM>wattr</EM><STRONG>_</STRONG><EM>off</EM>, and <EM>wattr</EM><STRONG>_</STRONG><EM>set</EM>), and some new (<EM>chgat</EM> and + its variants, <EM>color</EM><STRONG>_</STRONG><EM>set</EM>, and <EM>wcolor</EM><STRONG>_</STRONG><EM>set</EM>). + + Different Unix systems used differently sized bit fields in <EM>chtype</EM> for + the character code and the color pair identifier, and took into account + platforms' different integer sizes (32- versus 64-bit). + + The following table showing the number of bits for <EM>A</EM><STRONG>_</STRONG><EM>COLOR</EM> and + <EM>A</EM><STRONG>_</STRONG><EM>CHARTEXT</EM> was gleaned from the <EM>curses</EM> header files for various + operating systems and architectures. The inferred architecture and + notes reflect the format and size of the defined constants as well as + clues such as the alternate character set implementation. A 32-bit + library can be used on a 64-bit system, but not necessarily the + converse. <STRONG>Bits</STRONG> <STRONG>Year</STRONG> <STRONG>System</STRONG> <STRONG>Arch</STRONG> <STRONG>Color</STRONG> <STRONG>Char</STRONG> <STRONG>Notes</STRONG> @@ -434,7 +427,7 @@ 1996 AIX 4.2 32 7 16 X/Open <EM>curses</EM> 1996 OSF/1 r4 32 6 16 X/Open <EM>curses</EM> 1997 HP-UX 11.00 32 6 8 X/Open <EM>curses</EM> - 2000 U/Win 32/64 7/31 16 uses <EM>chtype</EM> + 2000 UWIN 32/64 7/31 16 uses <EM>chtype</EM> Notes: @@ -444,60 +437,59 @@ in 1996. <STRONG>o</STRONG> HP-UX 10.30 (1997) marked "curses_colr" obsolete. That version - of curses was dropped with HP-UX 11.30 in 2006. + of <EM>curses</EM> was dropped with HP-UX 11.30 in 2006. Regarding OSF/1 (and Tru64), - <STRONG>o</STRONG> These used 64-bit hardware. Like <EM>ncurses</EM>, the OSF/1 curses + <STRONG>o</STRONG> These used 64-bit hardware. Like <EM>ncurses</EM>, the OSF/1 <EM>curses</EM> interface is not customized for 32-bit and 64-bit versions. <STRONG>o</STRONG> Unlike other systems which evolved from AT&T code, OSF/1 - provided a new implementation for X/Open curses. + provided a new implementation for X/Open Curses. Regarding Solaris, <STRONG>o</STRONG> The initial release of Solaris was in 1992. - <STRONG>o</STRONG> The <EM>xpg4</EM> (X/Open) curses was developed by MKS from 1990 to 1995. - Sun's copyright began in 1996. + <STRONG>o</STRONG> Its XPG4 (X/Open Curses-conforming) <EM>xcurses</EM> library was + developed by Mortice Kern Systems from 1990 to 1995. Sun's + copyright began in 1996. - <STRONG>o</STRONG> Sun updated the X/Open curses interface after 64-bit support was - introduced in 1997, but did not modify the SVr4 curses + <STRONG>o</STRONG> Sun updated the X/Open Curses interface after 64-bit support was + introduced in 1997, but did not modify the SVr4 <EM>curses</EM> interface. - Regarding U/Win, + Regarding UWIN, - <STRONG>o</STRONG> Development of the curses library began in 1991, stopped in + <STRONG>o</STRONG> Development of the <EM>curses</EM> library began in 1991, stopped in 2000. <STRONG>o</STRONG> Color support was added in 1998. - <STRONG>o</STRONG> The library uses only <STRONG>chtype</STRONG> (no <STRONG>cchar_t</STRONG>). + <STRONG>o</STRONG> The library uses only <EM>chtype</EM> (not <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>). - Once X/Open curses was adopted in the mid-1990s, the constraint of a - 32-bit interface with many colors and wide-characters for <STRONG>chtype</STRONG> became - a moot point. The <STRONG>cchar_t</STRONG> structure (whose size and members are not + Once X/Open Curses was adopted in the mid-1990s, the constraint of a + 32-bit interface with many colors and wide-characters for <EM>chtype</EM> became + a moot point. The <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> structure (whose size and members are not specified in X/Open Curses) could be extended as needed. - Other interfaces are rarely used now: + Other interfaces are rarely used now. - <STRONG>o</STRONG> BSD curses was improved slightly in 1993/1994 using Keith Bostic's - modification to make the library 8-bit clean for <STRONG>nvi(1)</STRONG>. He moved - <EM>standout</EM> attribute to a structure member. + <STRONG>o</STRONG> BSD <EM>curses</EM> was improved slightly in 1993/1994 using Keith Bostic's + modification to make the library 8-bit clean for <STRONG>nvi(1)</STRONG>. He moved + the <EM>standout</EM> attribute to a structure member. The resulting 4.4BSD + <EM>curses</EM> was replaced by <EM>ncurses</EM> over the next ten years. - The resulting 4.4BSD curses was replaced by <EM>ncurses</EM> over the next - ten years. + <STRONG>o</STRONG> UWIN has been defunct since 2012. - <STRONG>o</STRONG> U/Win is rarely used now. + <EM>ncurses</EM> 6.0 (2015) added the <EM>A</EM><STRONG>_</STRONG><EM>ITALIC</EM> macro. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>, <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>, <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - -ncurses 6.5 2024-04-27 <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_beep.3x.html b/doc/html/man/curs_beep.3x.html index e3d6c81786db..76f78a40709e 100644 --- a/doc/html/man/curs_beep.3x.html +++ b/doc/html/man/curs_beep.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2005,2010 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_beep.3x,v 1.29 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_beep.3x,v 1.42 2025/02/01 23:46:11 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_beep 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_beep 3x 2025-02-01 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_beep 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_beep 3x 2025-02-01 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_beep.3x.html">curs_beep(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_beep.3x.html">curs_beep(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>beep</STRONG>, <STRONG>flash</STRONG> - ring the (visual) bell of the terminal with <EM>curses</EM> @@ -58,35 +56,45 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The <STRONG>beep</STRONG> and <STRONG>flash</STRONG> routines are used to alert the terminal user. The - routine <STRONG>beep</STRONG> sounds an audible alarm on the terminal, if possible; - otherwise it flashes the screen (visible bell). The routine <STRONG>flash</STRONG> - flashes the screen, and if that is not possible, sounds the alert. If - neither alert is possible, nothing happens. Nearly all terminals have - an audible alert (bell or beep), but only some can flash the screen. + <STRONG>beep</STRONG> and <STRONG>flash</STRONG> alert the terminal user: the former by sounding the + terminal's audible alarm, and the latter by visibly attracting + attention. Commonly, a terminal implements a visual bell by + momentarily reversing the character foreground and background colors on + the entire display; even a monochrome device can do this. These + functions each attempt the other alert type if the one requested is + unavailable. If neither is available, <EM>curses</EM> performs no action. + Nearly all terminals have an audible alert mechanism such as a bell or + piezoelectric buzzer, but only some can flash the screen. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - These routines return <STRONG>OK</STRONG> if they succeed in beeping or flashing, <STRONG>ERR</STRONG> - otherwise. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. + + In <EM>ncurses</EM>, <STRONG>beep</STRONG> and <STRONG>flash</STRONG> return <STRONG>OK</STRONG> if the terminal type supports the + corresponding capability: <STRONG>bell</STRONG> (<STRONG>bel</STRONG>) for <STRONG>beep</STRONG> and <STRONG>flash_screen</STRONG> (<STRONG>flash</STRONG>) + for <STRONG>flash</STRONG>. Otherwise they return <STRONG>ERR</STRONG>. </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - SVr4's beep and flash routines always returned <STRONG>OK</STRONG>, so it was not - possible to tell when the beep or flash failed. + In <EM>ncurses</EM>, these functions can return <STRONG>ERR</STRONG>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. Like SVr4, it - specifies that they always return <STRONG>OK</STRONG>. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + On SVr4 <EM>curses</EM>, they always return <EM>OK</EM>, and X/Open Curses specifies them + as doing so. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr2 (1984) introduced <EM>beep</EM> and <EM>flash</EM>. +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_beep.3x.html">curs_beep(3x)</A></STRONG> +ncurses 6.6 2025-02-01 <STRONG><A HREF="curs_beep.3x.html">curs_beep(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -96,6 +104,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_bkgd.3x.html b/doc/html/man/curs_bkgd.3x.html index 47d2e13b829f..a4d2a2e3b26a 100644 --- a/doc/html/man/curs_bkgd.3x.html +++ b/doc/html/man/curs_bkgd.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_bkgd.3x,v 1.61 2024/04/20 18:54:36 tom Exp @ + * @Id: curs_bkgd.3x,v 1.76 2025/08/23 22:39:20 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_bkgd 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_bkgd 3x 2025-08-23 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_bkgd 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_bkgd 3x 2025-08-23 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>bkgdset</STRONG>, <STRONG>wbkgdset</STRONG>, <STRONG>bkgd</STRONG>, <STRONG>wbkgd</STRONG>, <STRONG>getbkgd</STRONG> - manipulate background of a <EM>curses</EM> window of characters @@ -64,24 +62,29 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The <EM>background</EM> of a <EM>curses</EM> window (in the library's non-"wide" - configuration) is a <EM>chtype</EM> combining a set of attributes (see - <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>) with a character called the <EM>blank</EM> <EM>character.</EM> + Every <EM>curses</EM> window has a <EM>background</EM> <EM>character</EM> property: in the + library's non-wide-character configuration, it is a <EM>curses</EM> character + (<EM>chtype</EM>) that combines a set of attributes (and, if colors are enabled, + a color pair identifier) with a character code. When erasing (parts + of) a window, <EM>curses</EM> replaces the erased cells with the background + character. + + <EM>curses</EM> also uses the background character when writing characters to a + populated window. - The blank character is a spacing character that populates a window's - character cells when their contents are erased without replacement. - The background's attributes are combined with all non-blank characters - written to the window, as with the <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> and <STRONG><A HREF="curs_insch.3x.html">winsch(3x)</A></STRONG> families - of functions. + <STRONG>o</STRONG> The attribute part of the background character combines with all + non-blank character cells in the window, as populated by the + <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> and <STRONG><A HREF="curs_insch.3x.html">winsch(3x)</A></STRONG> families of functions (and those that + call them). - The blank character and attributes of the background combine with - characters written to the window as described below. The background - becomes a property of the character and moves with it through any - scrolling and insert/delete line/character operations. + <STRONG>o</STRONG> Both the character code and attributes of the background character + combine with blank character cells in the window. - To the extent possible on a given terminal, the attribute part of the - background is displayed as the graphic rendition of the character put - on the screen. + The background character's set of attributes becomes a property of the + character cell and move with it through any scrolling and insert/delete + line/character operations. To the extent possible on the terminal + type, <EM>curses</EM> displays the attributes of the background character as the + graphic rendition of a character cell on the display. </PRE><H3><a name="h3-bkgd_wbkgd">bkgd, wbkgd</a></H3><PRE> @@ -95,38 +98,40 @@ <STRONG>o</STRONG> Wherever the former background character appears, it changes to the new background character. - <EM>ncurses</EM> updates the rendition of each character cell by comparing the - character, non-color attributes, and colors. The library applies to - following procedure to each cell in the window, whether or not it is - blank. + <EM>ncurses</EM> updates the rendition of each character cell by comparing the + character, non-color attributes, and color pair selection. The library + applies the following procedure to each cell in the window, whether or + not it is blank. <STRONG>o</STRONG> <EM>ncurses</EM> first compares the cell's character to the previously - specified blank character; if they match, <EM>ncurses</EM> writes the new - blank character to the cell. + specified background character; if they match, <EM>ncurses</EM> writes the + new background character to the cell. - <STRONG>o</STRONG> <EM>ncurses</EM> then checks if the cell uses color, that is, its color pair - value is nonzero. If not, it simply replaces the attributes and - color pair in the cell with those from the new background + <STRONG>o</STRONG> <EM>ncurses</EM> then checks whether the cell uses color; that is, its color + pair value is nonzero. If not, it simply replaces the attributes + and color pair in the cell with those from the new background character. - <STRONG>o</STRONG> If the cell uses color, and its background color matches that of - the current window background, <EM>ncurses</EM> removes attributes that may - have come from the current background and adds those from the new - background. It finishes by setting the cell's background to use + <STRONG>o</STRONG> If the cell uses color, and its background color matches that of + the current window background, <EM>ncurses</EM> removes attributes that may + have come from the current background and adds those from the new + background. It finishes by setting the cell's background to use the new window background color. - <STRONG>o</STRONG> If the cell uses color, and its background color does not match - that of the current window background, <EM>ncurses</EM> updates only the - non-color attributes, first removing those that may have come from - the current background, and then adding attributes from the new + <STRONG>o</STRONG> If the cell uses color, and its background color does not match + that of the current window background, <EM>ncurses</EM> updates only the + non-color attributes, first removing those that may have come from + the current background, and then adding attributes from the new background. - <EM>ncurses</EM> treats a background character value of zero (0) as a blank - character. + If the new background's character is non-spacing (for example, if it is + a control character), <EM>ncurses</EM> retains the existing background + character, except for one special case: <EM>ncurses</EM> treats a background + character code of zero (0) as a space. If the terminal does not support color, or if color has not been initialized with <STRONG><A HREF="curs_color.3x.html">start_color(3x)</A></STRONG>, <EM>ncurses</EM> ignores the new background - character's color attribute. + character's color pair selection. </PRE><H3><a name="h3-bkgdset_wbkgdset">bkgdset, wbkgdset</a></H3><PRE> @@ -136,19 +141,21 @@ </PRE><H3><a name="h3-getbkgd">getbkgd</a></H3><PRE> - <STRONG>getbkgd</STRONG> obtains the given window's background character and attribute - combination. + <STRONG>getbkgd</STRONG> returns the given window's background character, attributes, + and color pair as a <EM>chtype</EM>. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Functions returning an <EM>int</EM> return <STRONG>OK</STRONG> on success. <STRONG>bkgd</STRONG> returns <STRONG>ERR</STRONG> if - the library has not been initialized. <STRONG>wbkgd</STRONG> and <STRONG>getbkgd</STRONG> return <STRONG>ERR</STRONG> if - a <EM>WINDOW</EM> pointer argument is null. - <STRONG>bkgdset</STRONG> and <STRONG>wbkgdset</STRONG> do not return a value. - <STRONG>getbkgd</STRONG> returns a window's background character and attribute - combination. + Functions returning an <EM>int</EM> return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success. + In <EM>ncurses</EM>, failure occurs if + + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, or + + <STRONG>o</STRONG> <EM>win</EM> is <EM>NULL</EM>. + + <STRONG>getbkgd</STRONG>'s return value is as described above. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> @@ -159,37 +166,39 @@ X/Open Curses mentions that the character part of the background must be a single-byte value. <EM>ncurses</EM>, like SVr4 <EM>curses</EM>, checks to ensure - that, and will reuse the old background character if the check fails. + that it is, and retains the existing background character if the check + fails. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. It specifies that - <STRONG>bkgd</STRONG>, <STRONG>wbkgd</STRONG>, and <STRONG>getbkgd</STRONG> return <STRONG>ERR</STRONG> on failure (in the case of the - last, this value is cast to <EM>chtype</EM>), but describes no failure - conditions. + X/Open Curses Issue 4 describes these functions. It indicates that + <EM>bkgd</EM>, <EM>wbkgd</EM>, and <EM>getbkgd</EM> return <EM>ERR</EM> on failure (in the case of the + last, this value is cast to <EM>chtype</EM>), but specifies no error conditions + for them. - The SVr4.0 manual says that <STRONG>bkgd</STRONG> and <STRONG>wbkgd</STRONG> may return <STRONG>OK</STRONG> "or a non- - negative integer if <STRONG>immedok</STRONG> is set", which refers to the return value - from <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, used to implement the immediate repainting. SVr4 - <EM>curses</EM>'s <STRONG>wrefresh</STRONG> returns the number of characters written to the - screen during the refresh. <EM>ncurses</EM> does not do that. + SVr4 documentation says that <EM>bkgd</EM> and <EM>wbkgd</EM> return <EM>OK</EM> "or a non- + negative integer if <EM>immedok()</EM> is set", referring to the return value + from <EM>wrefresh</EM>, which in SVr4 returns a count of characters written to + the window if its <EM>immedok</EM> property is set; in <EM>ncurses</EM>, it does not. Neither X/Open Curses nor the SVr4 manual pages detail how the - rendition of characters on the screen updates when <STRONG>bkgd</STRONG> or <STRONG>wbkgd</STRONG> + rendition of characters in the window updates when <EM>bkgd</EM> or <EM>wbkgd</EM> changes the background character. <EM>ncurses</EM>, like SVr4 <EM>curses</EM>, does not - (in its non-"wide" configuration) store the background and window - attribute contributions to each character cell separately. + (in its non-wide-character configuration) store the background and + window attribute contributions to each character cell separately. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr3.1 (1987) introduced these functions. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG> describes the corresponding functions in the "wide" + <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG> describes the corresponding functions in the wide configuration of <EM>ncurses</EM>. <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG> +ncurses 6.6 2025-08-23 <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -205,6 +214,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_bkgrnd.3x.html b/doc/html/man/curs_bkgrnd.3x.html index a11a68c57a7b..b0a04b68ecb1 100644 --- a/doc/html/man/curs_bkgrnd.3x.html +++ b/doc/html/man/curs_bkgrnd.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2002-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_bkgrnd.3x,v 1.42 2024/04/20 18:54:36 tom Exp @ + * @Id: curs_bkgrnd.3x,v 1.60 2025/08/23 22:39:20 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_bkgrnd 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_bkgrnd 3x 2025-08-23 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_bkgrnd 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_bkgrnd 3x 2025-08-23 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>bkgrnd</STRONG>, <STRONG>wbkgrnd</STRONG>, <STRONG>bkgrndset</STRONG>, <STRONG>wbkgrndset</STRONG>, <STRONG>getbkgrnd</STRONG>, <STRONG>wgetbkgrnd</STRONG> - manipulate background of a <EM>curses</EM> window of wide characters @@ -65,24 +63,29 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The <EM>background</EM> of a <EM>curses</EM> window (in the library's "wide" - configuration) is a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> combining a set of attributes (see - <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>) with a complex character called the <EM>blank</EM> <EM>character.</EM> + Every <EM>curses</EM> window has a <EM>background</EM> <EM>character</EM> property: in the + library's wide configuration, it is a <EM>curses</EM> complex character + (<EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>) that combines a set of attributes (and, if colors are + enabled, a color pair identifier) with a character code. When erasing + (parts of) a window, <EM>curses</EM> replaces the erased cells with the + background character. - The blank character is a spacing character that populates a window's - character cells when their contents are erased without replacement. - The background's attributes are combined with all non-blank characters - written to the window, as with the <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> and <STRONG><A HREF="curs_ins_wch.3x.html">wins_wch(3x)</A></STRONG> - families of functions. + <EM>curses</EM> also uses the background character when writing characters to a + populated window. - The blank character and attributes of the background combine with - characters written to the window as described below. The background - becomes a property of the character and moves with it through any - scrolling and insert/delete line/character operations. + <STRONG>o</STRONG> The attribute part of the background character combines with all + non-blank character cells in the window, as populated by the + <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> and <STRONG><A HREF="curs_ins_wch.3x.html">wins_wch(3x)</A></STRONG> families of functions (and those that + call them). - To the extent possible on a given terminal, the attribute part of the - background is displayed as the graphic rendition of the character put - on the screen. + <STRONG>o</STRONG> Both the character code and attributes of the background character + combine with blank character cells in the window. + + The background character's set of attributes becomes a property of the + character cell and move with it through any scrolling and insert/delete + line/character operations. To the extent possible on the terminal + type, <EM>curses</EM> displays the attributes of the background character as the + graphic rendition of a character cell on the display. </PRE><H3><a name="h3-bkgrnd_wbkgrnd">bkgrnd, wbkgrnd</a></H3><PRE> @@ -90,24 +93,24 @@ specified window and then apply this setting to every character cell in that window. - <STRONG>o</STRONG> The rendition of every character in the window changes to the new + <STRONG>o</STRONG> The rendition of every character in the window changes to the new background rendition. <STRONG>o</STRONG> Wherever the former background character appears, it changes to the new background character. <EM>ncurses</EM> updates the rendition of each character cell by comparing the - character, non-color attributes, and colors. The library applies to - following procedure to each cell in the window, whether or not it is - blank. + character, non-color attributes, and color pair selection. The library + applies to following procedure to each cell in the window, whether or + not it is blank. - <STRONG>o</STRONG> <EM>ncurses</EM> first compares the cell's character to the previously - specified blank character; if they match, <EM>ncurses</EM> writes the new - blank character to the cell. + <STRONG>o</STRONG> <EM>ncurses</EM> first compares the cell's character to the previously + specified background character; if they match, <EM>ncurses</EM> writes the + new background character to the cell. - <STRONG>o</STRONG> <EM>ncurses</EM> then checks if the cell uses color, that is, its color pair - value is nonzero. If not, it simply replaces the attributes and - color pair in the cell with those from the new background + <STRONG>o</STRONG> <EM>ncurses</EM> then checks whether the cell uses color; that is, its color + pair value is nonzero. If not, it simply replaces the attributes + and color pair in the cell with those from the new background character. <STRONG>o</STRONG> If the cell uses color, and its background color matches that of @@ -122,12 +125,13 @@ the current background, and then adding attributes from the new background. - <EM>ncurses</EM> treats a background character value of zero (0) as a blank - character. + If the new background's character is non-spacing, <EM>ncurses</EM> reuses the + old background character, except for one special case: <EM>ncurses</EM> treats a + background character code of zero (0) as a space. If the terminal does not support color, or if color has not been initialized with <STRONG><A HREF="curs_color.3x.html">start_color(3x)</A></STRONG>, <EM>ncurses</EM> ignores the new background - character's color attribute. + character's color pair selection. </PRE><H3><a name="h3-bkgrndset_wbkgrndset">bkgrndset, wbkgrndset</a></H3><PRE> @@ -137,47 +141,53 @@ </PRE><H3><a name="h3-getbkgrnd_wgetbkgrnd">getbkgrnd, wgetbkgrnd</a></H3><PRE> - The <STRONG>getbkgrnd</STRONG> and <STRONG>wgetbkgrnd</STRONG> functions obtain the background character - and attribute pair of <STRONG>stdscr</STRONG> or the specified window and store it via - the <EM>wch</EM> pointer. + <STRONG>getbkgrnd</STRONG> and <STRONG>wgetbkgrnd</STRONG> respectively obtain <STRONG>stdscr</STRONG>'s or the given + window's background character, attributes, and color pair, and store it + in their <EM>wch</EM> argument. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> <STRONG>bkgrndset</STRONG> and <STRONG>wbkgrndset</STRONG> do not return a value. - The other functions return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success. In - <EM>ncurses</EM>, failure occurs if + Functions returning an <EM>int</EM> return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success. + In <EM>ncurses</EM>, failure occurs if + + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> a <EM>WINDOW</EM> pointer <EM>win</EM> is null, or + <STRONG>o</STRONG> <EM>win</EM> is <EM>NULL</EM>, or - <STRONG>o</STRONG> a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> pointer <EM>wch</EM> is null. + <STRONG>o</STRONG> <EM>wch</EM> is <EM>NULL</EM>. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> <STRONG>bkgrnd</STRONG>, <STRONG>bkgrndset</STRONG>, and <STRONG>getbkgrnd</STRONG> may be implemented as macros. - Unlike their counterparts in the non-"wide" configuration of <EM>ncurses</EM>, - <STRONG>getbkgrnd</STRONG> and <STRONG>wgetbkgrnd</STRONG> supply the background character and attribute - in a modifiable <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> parameter, not as the return value. + Unlike their counterparts in the non-wide-character configuration of + <EM>ncurses</EM>, <STRONG>getbkgrnd</STRONG> and <STRONG>wgetbkgrnd</STRONG> store the background character in a + modifiable <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> parameter, rather than supplying it as the return + value. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. It specifies no - error conditions for them. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. X/Open Curses does not provide details of how the rendition is updated. - This implementation follows the approach used in SVr4 <EM>curses</EM>. + <EM>ncurses</EM> follows the approach used in SVr4 <EM>curses</EM>'s non-wide functions + for manipulating the window background. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG> describes the corresponding functions in the non-"wide" - configuration of <EM>ncurses</EM>. +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + X/Open Curses Issue 4 (1995) initially specified these functions. - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG> describes the corresponding functions in the non-wide- + character configuration of <EM>ncurses</EM>. + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG> +ncurses 6.6 2025-08-23 <STRONG><A HREF="curs_bkgrnd.3x.html">curs_bkgrnd(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -193,6 +203,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF=" <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_border.3x.html b/doc/html/man/curs_border.3x.html index d310dad798ca..ef90c8eab1d8 100644 --- a/doc/html/man/curs_border.3x.html +++ b/doc/html/man/curs_border.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2007,2010 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_border.3x,v 1.49 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_border.3x,v 1.65 2025/10/20 23:42:24 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_border 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_border 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_border 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_border 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>border</STRONG>, <STRONG>wborder</STRONG>, <STRONG>box</STRONG>, <STRONG>hline</STRONG>, <STRONG>whline</STRONG>, <STRONG>vline</STRONG>, <STRONG>wvline</STRONG>, <STRONG>mvhline</STRONG>, <STRONG>mvwhline</STRONG>, <STRONG>mvvline</STRONG>, <STRONG>mvwvline</STRONG> - draw borders and lines in a <EM>curses</EM> window of @@ -56,29 +54,28 @@ <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> <STRONG>int</STRONG> <STRONG>border(chtype</STRONG> <EM>ls</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>rs</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ts</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>bs</EM><STRONG>,</STRONG> - <STRONG>chtype</STRONG> <EM>tl</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>tr</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>bl</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>br</EM><STRONG>);</STRONG> + <STRONG>chtype</STRONG> <EM>tl</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>tr</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>bl</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>br</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>wborder(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ls</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>rs</EM><STRONG>,</STRONG> - <STRONG>chtype</STRONG> <EM>ts</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>bs</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>tl</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>tr</EM><STRONG>,</STRONG> - <STRONG>chtype</STRONG> <EM>bl</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>br</EM><STRONG>);</STRONG> + <STRONG>chtype</STRONG> <EM>ts</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>bs</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>tl</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>tr</EM><STRONG>,</STRONG> + <STRONG>chtype</STRONG> <EM>bl</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>br</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>box(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>verch</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>horch</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>hline(chtype</STRONG> <EM>ch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>whline(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>vline(chtype</STRONG> <EM>ch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wvline(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvhline(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>mvwhline(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>vline(chtype</STRONG> <EM>ch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wvline(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>mvvline(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>mvwvline(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The <STRONG>border</STRONG>, <STRONG>wborder</STRONG> and <STRONG>box</STRONG> routines draw a box around the edges of a - window. Other than the window, each argument is a character with - attributes: - + <STRONG>wborder</STRONG> and <STRONG>border</STRONG> draw a box at the edges of the specified window or + <STRONG>stdscr</STRONG>, respectively. Each <EM>chtype</EM> argument corresponds to a geometric + component of the border as follows: <EM>ls</EM> - left side, <EM>rs</EM> - right side, <EM>ts</EM> - top side, @@ -88,60 +85,76 @@ <EM>bl</EM> - bottom left-hand corner, and <EM>br</EM> - bottom right-hand corner. - If any of these arguments is zero, then the corresponding default - values (defined in <STRONG>curses.h</STRONG>) are used instead: - + If any <EM>chtype</EM> argument is <STRONG>0</STRONG>, then <EM>curses</EM> uses forms-drawing characters + (see <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>) in the following correspondence: <STRONG>ACS_VLINE</STRONG>, <STRONG>ACS_VLINE</STRONG>, <STRONG>ACS_HLINE</STRONG>, <STRONG>ACS_HLINE</STRONG>, <STRONG>ACS_ULCORNER</STRONG>, <STRONG>ACS_URCORNER</STRONG>, - <STRONG>ACS_LLCORNER</STRONG>, + <STRONG>ACS_LLCORNER</STRONG>, and <STRONG>ACS_LRCORNER</STRONG>. - <STRONG>box(</STRONG><EM>win</EM><STRONG>,</STRONG> <EM>verch</EM><STRONG>,</STRONG> <EM>horch</EM><STRONG>)</STRONG> is a shorthand for the following call: - <STRONG>wborder(</STRONG><EM>win</EM><STRONG>,</STRONG> <EM>verch</EM><STRONG>,</STRONG> <EM>verch</EM><STRONG>,</STRONG> <EM>horch</EM><STRONG>,</STRONG> <EM>horch</EM><STRONG>,</STRONG> <STRONG>0,</STRONG> <STRONG>0,</STRONG> <STRONG>0,</STRONG> <STRONG>0)</STRONG>. - - The <STRONG>hline</STRONG> and <STRONG>whline</STRONG> functions draw a horizontal (left to right) line - using <EM>ch</EM> starting at the current cursor position in the window. The - current cursor position is not changed. The line is at most <EM>n</EM> - characters long, or as many as fit into the window. + <STRONG>box(</STRONG><EM>win</EM><STRONG>,</STRONG> <EM>verch</EM><STRONG>,</STRONG> <EM>horch</EM><STRONG>)</STRONG> is shorthand for "<STRONG>wborder(</STRONG><EM>win</EM><STRONG>,</STRONG> <EM>verch</EM><STRONG>,</STRONG> <EM>verch</EM><STRONG>,</STRONG> + <EM>horch</EM><STRONG>,</STRONG> <EM>horch</EM><STRONG>,</STRONG> <STRONG>0,</STRONG> <STRONG>0,</STRONG> <STRONG>0,</STRONG> <STRONG>0)</STRONG>". - The <STRONG>vline</STRONG> and <STRONG>wvline</STRONG> functions draw a vertical (top to bottom) line - using <EM>ch</EM> starting at the current cursor position in the window. The - current cursor position is not changed. The line is at most <EM>n</EM> - characters long, or as many as fit into the window. + <STRONG>whline</STRONG> draws a horizontal line of <EM>ch</EM> from left to right, and <STRONG>wvline</STRONG> a + vertical one from top to bottom, stopping once <EM>n</EM> characters have been + drawn or upon reaching the boundary of <EM>win</EM>. These functions do not + update the cursor position (beyond any motion directed by their "mv" + variants). <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All routines return the integer <STRONG>OK</STRONG>. The SVr4.0 manual says "or a non- - negative integer if <STRONG>immedok</STRONG> is set", but this appears to be an error. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - X/Open Curses does not specify any error conditions. This - implementation returns an error if the window pointer is null. + In <EM>ncurses</EM>, - Functions prefixed with "mv" first perform cursor movement and fail if + <STRONG>o</STRONG> these functions fail if the screen is not initialized; and + + <STRONG>o</STRONG> functions taking a <EM>WINDOW</EM> pointer argument fail if <EM>win</EM> is a null + pointer. + + Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - The borders generated by these functions are <EM>inside</EM> borders (this is - also true of SVr4 curses, though the fact is not documented). + Unusually, there is no <STRONG>wbox</STRONG> function; <STRONG>box</STRONG> behaves as one would expect + <STRONG>wbox</STRONG> to, accepting a <EM>WINDOW</EM> pointer argument. + + <STRONG>border</STRONG>, <STRONG>box</STRONG>, <STRONG>hline</STRONG>, <STRONG>mvhline</STRONG>, <STRONG>mvwhline</STRONG>, <STRONG>vline</STRONG>, <STRONG>mvvline</STRONG>, and <STRONG>mvwvline</STRONG> may + be implemented as macros. - Note that <STRONG>border</STRONG> and <STRONG>box</STRONG> may be macros. + Borders drawn by these functions are <EM>interior</EM> borders. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. + These functions are described in X/Open Curses Issue 4. It specifies + no error conditions for them. + SVr4 documentation says that these functions return <EM>OK</EM> "or a non- + negative integer if <EM>immedok()</EM> is set", referring to the return value + from <EM>wrefresh</EM>, which in SVr4 returns a count of characters written to + the window if its <EM>immedok</EM> property is set; in <EM>ncurses</EM>, it does not. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> + BSD <EM>curses</EM> drew boxes with <EM>horch</EM> in <EM>every</EM> character cell of the top and + bottom lines of the window, whereas SVr3.1 and later <EM>curses</EM>, because + its <EM>box</EM> wrapped <EM>wborder</EM>, used the default corner characters. +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced <EM>box</EM>, defining it as a function. + + SVr3.1 (1987) added <EM>whline</EM> and <EM>wvline</EM> and their variants, as well as + <EM>border</EM> and <EM>wborder</EM>, redefining <EM>box</EM> as a macro wrapping the latter. + + +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -151,6 +164,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF=" <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_border_set.3x.html b/doc/html/man/curs_border_set.3x.html index e687aa68a87a..a75ac0cde163 100644 --- a/doc/html/man/curs_border_set.3x.html +++ b/doc/html/man/curs_border_set.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 2002-2011,2012 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_border_set.3x,v 1.36 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_border_set.3x,v 1.50 2025/10/21 00:10:56 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_border_set 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_border_set 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_border_set 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_border_set 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>border_set</STRONG>, <STRONG>wborder_set</STRONG>, <STRONG>box_set</STRONG>, <STRONG>hline_set</STRONG>, <STRONG>whline_set</STRONG>, <STRONG>mvhline_set</STRONG>, <STRONG>mvwhline_set</STRONG>, <STRONG>vline_set</STRONG>, <STRONG>wvline_set</STRONG>, <STRONG>mvvline_set</STRONG>, <STRONG>mvwvline_set</STRONG> - draw @@ -55,53 +53,38 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>border_set(</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>ls</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>rs</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>ts</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>bs</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>tl</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>tr</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>bl</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>br</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wborder_set(</STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>ls</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>rs</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>ts</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>bs</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>tl</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>tr</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>bl</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>br</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>box_set(</STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>verch</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>horch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>hline_set(</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>whline_set(</STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvhline_set(</STRONG> - <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwhline_set(</STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> - <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>vline_set(</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wvline_set(</STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvvline_set(</STRONG> - <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwvline_set(</STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> - <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>border_set(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>ls</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>rs</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>ts</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>bs</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>tl</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>tr</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>bl</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>br</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wborder_set(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>ls</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>rs</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>ts</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>bs</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>tl</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>tr</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>bl</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>br</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>box_set(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>verch</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>horch</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>hline_set(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>whline_set(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvhline_set(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwhline_set(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>vline_set(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wvline_set(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvvline_set(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwvline_set(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The <STRONG>border_set</STRONG> and <STRONG>wborder_set</STRONG> functions draw a border around the edges - of the current or specified window. These functions do not change the + of the current or specified window. These functions do not change the cursor position, and do not wrap. - Other than the window, each argument is a complex character with + Other than the window, each argument is a complex character with attributes: <EM>ls</EM> - left side, <EM>rs</EM> - right side, @@ -112,7 +95,7 @@ <EM>bl</EM> - bottom left-hand corner, and <EM>br</EM> - bottom right-hand corner. - If any of these arguments is zero, then the corresponding default + If any of these arguments is zero, then the corresponding default values (defined in <STRONG>curses.h</STRONG>) are used instead: <STRONG>WACS_VLINE</STRONG>, <STRONG>WACS_VLINE</STRONG>, @@ -128,9 +111,9 @@ <STRONG>wborder_set(</STRONG><EM>win</EM><STRONG>,</STRONG> <EM>verch</EM><STRONG>,</STRONG> <EM>verch</EM><STRONG>,</STRONG> <EM>horch</EM><STRONG>,</STRONG> <EM>horch</EM><STRONG>,</STRONG> <STRONG>NULL,</STRONG> <STRONG>NULL,</STRONG> <STRONG>NULL,</STRONG> <STRONG>NULL);</STRONG> - The <STRONG>*line_set</STRONG> functions use <EM>wch</EM> to draw a line starting at the current - cursor position in the window. The line is at most <EM>n</EM> characters long - or as many as fit into the window. The current cursor position is not + The <STRONG>*line_set</STRONG> functions use <EM>wch</EM> to draw a line starting at the current + cursor position in the window. The line is at most <EM>n</EM> characters long + or as many as fit into the window. The current cursor position is not changed. The <STRONG>hline_set</STRONG>, <STRONG>mvhline_set</STRONG>, <STRONG>mvwhline_set</STRONG>, and <STRONG>whline_set</STRONG> functions draw @@ -144,27 +127,30 @@ Upon successful completion, these functions return <STRONG>OK</STRONG>. Otherwise, they return <STRONG>ERR</STRONG>. - Functions using a window parameter return an error if it is null. + Functions using a window parameter return <STRONG>ERR</STRONG> if it is null. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that <STRONG>border_set</STRONG>, <STRONG>hline_set</STRONG>, <STRONG>mvhline_set</STRONG>, <STRONG>mvvline_set</STRONG>, - <STRONG>mvwhline_set</STRONG>, <STRONG>mvwvline_set</STRONG>, and <STRONG>vline_set</STRONG> may be macros. + <STRONG>border_set</STRONG>, <STRONG>hline_set</STRONG>, <STRONG>mvhline_set</STRONG>, <STRONG>mvvline_set</STRONG>, <STRONG>mvwhline_set</STRONG>, + <STRONG>mvwvline_set</STRONG>, and <STRONG>vline_set</STRONG> may be implemented as macros. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + X/Open Curses Issue 4 (1995) initially specified these functions. +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -174,6 +160,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="curs <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_clear.3x.html b/doc/html/man/curs_clear.3x.html index 058689bfc827..d4a63c080ce5 100644 --- a/doc/html/man/curs_clear.3x.html +++ b/doc/html/man/curs_clear.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2016 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_clear.3x,v 1.48 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_clear.3x,v 1.58 2025/01/19 00:49:39 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_clear 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_clear 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_clear 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_clear 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>erase</STRONG>, <STRONG>werase</STRONG>, <STRONG>clear</STRONG>, <STRONG>wclear</STRONG>, <STRONG>clrtobot</STRONG>, <STRONG>wclrtobot</STRONG>, <STRONG>clrtoeol</STRONG>, <STRONG>wclrtoeol</STRONG> - clear all or part of a <EM>curses</EM> window @@ -78,8 +76,8 @@ </PRE><H3><a name="h3-clear_wclear">clear, wclear</a></H3><PRE> - The <STRONG>clear</STRONG> and <STRONG>wclear</STRONG> routines are like <STRONG>erase</STRONG> and <STRONG>werase</STRONG>, but they also - call <STRONG><A HREF="curs_outopts.3x.html">clearok(3x)</A></STRONG>, so that the screen is cleared completely on the next + The <STRONG>clear</STRONG> and <STRONG>wclear</STRONG> routines are like <STRONG>erase</STRONG> and <STRONG>werase</STRONG>, but they also + call <STRONG><A HREF="curs_outopts.3x.html">clearok(3x)</A></STRONG>, so that the screen is cleared completely on the next call to <STRONG>wrefresh</STRONG> for that window and repainted from scratch. @@ -98,34 +96,34 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> All routines return the integer <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - X/Open defines no error conditions. In this implementation, + In this implementation, - <STRONG>o</STRONG> functions using a window pointer parameter return an error if it is - null + <STRONG>o</STRONG> functions using a window pointer parameter return <STRONG>ERR</STRONG> if it is null <STRONG>o</STRONG> <STRONG>wclrtoeol</STRONG> returns an error if the cursor position is about to wrap. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that <STRONG>erase</STRONG>, <STRONG>werase</STRONG>, <STRONG>clear</STRONG>, <STRONG>wclear</STRONG>, <STRONG>clrtobot</STRONG>, and <STRONG>clrtoeol</STRONG> may be - macros. + <STRONG>erase</STRONG>, <STRONG>werase</STRONG>, <STRONG>clear</STRONG>, <STRONG>wclear</STRONG>, <STRONG>clrtobot</STRONG>, and <STRONG>clrtoeol</STRONG> may be implemented + as macros. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - The SVr4.0 manual says that these functions could return "or a non- - negative integer if <STRONG>immedok</STRONG> is set", referring to the return-value of - <STRONG>wrefresh</STRONG>. In that implementation, <STRONG>wrefresh</STRONG> would return a count of the - number of characters written to the terminal. + SVr4 documentation says that these functions return <EM>OK</EM> "or a non- + negative integer if <EM>immedok()</EM> is set", referring to the return value + from <EM>wrefresh</EM>, which in SVr4 returns a count of characters written to + the window if its <EM>immedok</EM> property is set; in <EM>ncurses</EM>, it does not. - Some historic curses implementations had, as an undocumented feature, + Some historic curses implementations had, as an undocumented feature, the ability to do the equivalent of <STRONG>clearok(...,</STRONG> <STRONG>1)</STRONG> by saying <STRONG>touchwin(stdscr)</STRONG> or <STRONG>clear(stdscr)</STRONG>. This will not work under <EM>ncurses</EM>. - This implementation, and others such as Solaris, sets the current - position to 0,0 after erasing via <STRONG>werase</STRONG> and <STRONG>wclear</STRONG>. That fact is not - documented in other implementations, and may not be true of + This implementation, and others such as Solaris, sets the current + position to 0,0 after erasing via <STRONG>werase</STRONG> and <STRONG>wclear</STRONG>. That fact is not + documented in other implementations, and may not be true of implementations which were not derived from SVr4 source. Not obvious from the description, most implementations clear the screen @@ -136,9 +134,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_color.3x.html b/doc/html/man/curs_color.3x.html index d84a5732540a..03d533d04d70 100644 --- a/doc/html/man/curs_color.3x.html +++ b/doc/html/man/curs_color.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,32 +27,30 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_color.3x,v 1.100 2024/04/20 21:24:19 tom Exp @ + * @Id: curs_color.3x,v 1.126 2025/08/23 22:39:20 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_color 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_color 3x 2025-08-23 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_color 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_color 3x 2025-08-23 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>start_color</STRONG>, <STRONG>has_colors</STRONG>, <STRONG>can_change_color</STRONG>, <STRONG>init_pair</STRONG>, <STRONG>init_color</STRONG>, <STRONG>init_extended_pair</STRONG>, <STRONG>init_extended_color</STRONG>, <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>, <STRONG>extended_color_content</STRONG>, <STRONG>extended_pair_content</STRONG>, <STRONG>reset_color_pairs</STRONG>, <STRONG>COLOR_PAIR</STRONG>, <STRONG>PAIR_NUMBER</STRONG>, <STRONG>COLORS</STRONG>, <STRONG>COLOR_PAIRS</STRONG>, <STRONG>COLOR_BLACK</STRONG>, <STRONG>COLOR_RED</STRONG>, <STRONG>COLOR_GREEN</STRONG>, <STRONG>COLOR_YELLOW</STRONG>, <STRONG>COLOR_BLUE</STRONG>, <STRONG>COLOR_MAGENTA</STRONG>, <STRONG>COLOR_CYAN</STRONG>, - <STRONG>COLOR_WHITE</STRONG> - manipulate terminal colors with <EM>curses</EM> + <STRONG>COLOR_WHITE</STRONG>, <STRONG>A_COLOR</STRONG> - manipulate terminal colors with <EM>curses</EM> </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> @@ -82,8 +80,18 @@ <EM>/*</EM> <EM>extension</EM> <EM>*/</EM> <STRONG>void</STRONG> <STRONG>reset_color_pairs(void);</STRONG> + <EM>/*</EM> <EM>macros</EM> <EM>*/</EM> <STRONG>int</STRONG> <STRONG>COLOR_PAIR(int</STRONG> <EM>n</EM><STRONG>);</STRONG> <STRONG>PAIR_NUMBER(int</STRONG> <EM>attr</EM><STRONG>);</STRONG> + <STRONG>COLOR_BLACK</STRONG> + <STRONG>COLOR_RED</STRONG> + <STRONG>COLOR_GREEN</STRONG> + <STRONG>COLOR_YELLOW</STRONG> + <STRONG>COLOR_BLUE</STRONG> + <STRONG>COLOR_MAGENTA</STRONG> + <STRONG>COLOR_CYAN</STRONG> + <STRONG>COLOR_WHITE</STRONG> + <STRONG>A_COLOR</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> @@ -99,39 +107,37 @@ If a terminal has the relevant capability, <STRONG>init_color</STRONG> permits (re)definition of a color. <STRONG>has_colors</STRONG> and <STRONG>can_change_color</STRONG> return <STRONG>TRUE</STRONG> - or <STRONG>FALSE</STRONG>, depending on whether the terminal has color capability and - whether the programmer can change the colors. <STRONG>color_content</STRONG> permits - extraction of the red, green, and blue components of an initialized - color. <STRONG>pair_content</STRONG> permits discovery of a color pair's current + or <STRONG>FALSE</STRONG>, depending on whether the terminal has color capability and + whether the programmer can change the colors. <STRONG>color_content</STRONG> permits + extraction of the red, green, and blue components of an initialized + color. <STRONG>pair_content</STRONG> permits discovery of a color pair's current definition. </PRE><H3><a name="h3-Rendering">Rendering</a></H3><PRE> - <EM>curses</EM> combines the following data to render a character cell. Any of + <EM>curses</EM> combines the following data to render a character cell. Any of them can include color information. <STRONG>o</STRONG> <EM>curses</EM> character attributes, as from <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> or <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> <STRONG>o</STRONG> window attributes, as from <STRONG><A HREF="curs_attr.3x.html">wattrset(3x)</A></STRONG> or <STRONG><A HREF="curs_attr.3x.html">wattr_set(3x)</A></STRONG> - <STRONG>o</STRONG> window background character attributes, as from <STRONG><A HREF="curs_bkgd.3x.html">wbkgdset(3x)</A></STRONG> or + <STRONG>o</STRONG> window background character attributes, as from <STRONG><A HREF="curs_bkgd.3x.html">wbkgdset(3x)</A></STRONG> or <STRONG><A HREF="curs_bkgrnd.3x.html">wbkgrndset(3x)</A></STRONG> - Per-character and window attributes are usually set through a function - parameter containing attributes including a color pair value. Some + Per-character and window attributes are usually set through a function + parameter containing attributes including a color pair value. Some functions, such as <STRONG>wattr_set</STRONG>, use a separate color pair number parameter. - The background character is a special case: it includes a character + The background character is a special case: it includes a character code, just as if it were passed to <STRONG>waddch</STRONG>. - The <EM>curses</EM> library does the actual work of combining these color pairs + The <EM>curses</EM> library does the actual work of combining these color pairs in an internal function called from <STRONG>waddch</STRONG>: <STRONG>o</STRONG> If the parameter passed to <STRONG>waddch</STRONG> is <EM>blank</EM>, and it uses the special - color pair 0, - - <STRONG>o</STRONG> <EM>curses</EM> next checks the window attribute. + color pair 0, <EM>curses</EM> next checks the window attribute. <STRONG>o</STRONG> If the window attribute does not use color pair 0, <EM>curses</EM> uses the color pair from the window attribute. @@ -149,32 +155,27 @@ </PRE><H2><a name="h2-CONSTANTS">CONSTANTS</a></H2><PRE> - In <STRONG><curses.h></STRONG> the following macros are defined. These are the standard - colors (ISO-6429). <EM>curses</EM> also assumes that <STRONG>COLOR_BLACK</STRONG> is the default - background color for all terminals. - - <STRONG>COLOR_BLACK</STRONG> - <STRONG>COLOR_RED</STRONG> - <STRONG>COLOR_GREEN</STRONG> - <STRONG>COLOR_YELLOW</STRONG> - <STRONG>COLOR_BLUE</STRONG> - <STRONG>COLOR_MAGENTA</STRONG> - <STRONG>COLOR_CYAN</STRONG> - <STRONG>COLOR_WHITE</STRONG> + ISO 6429 and ECMA-48 define eight standard colors (also known as "ANSI" + colors). <EM>curses.h</EM> defines object-like macros <STRONG>COLOR_BLACK</STRONG>, <STRONG>COLOR_RED</STRONG>, + <STRONG>COLOR_GREEN</STRONG>, <STRONG>COLOR_YELLOW</STRONG>, <STRONG>COLOR_BLUE</STRONG>, <STRONG>COLOR_MAGENTA</STRONG>, <STRONG>COLOR_CYAN</STRONG>, and + <STRONG>COLOR_WHITE</STRONG> accordingly. <EM>curses</EM> assumes that <STRONG>COLOR_BLACK</STRONG> is the + default background color for all terminals. <EM>ncurses</EM> offers an + extension to override that assumption; see <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG>. + Some terminals support additional colors that lack standard names. - Some terminals support more than the eight (8) "ANSI" colors. There - are no standard names for those additional colors. + <STRONG>A_COLOR</STRONG> is a bit mask that, when bitwise "and"-ed with a <EM>chtype</EM>, + extracts its color pair identifier. </PRE><H2><a name="h2-VARIABLES">VARIABLES</a></H2><PRE> </PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE> - is initialized by <STRONG>start_color</STRONG> to the maximum number of colors the + is initialized by <STRONG>start_color</STRONG> to the maximum number of colors the terminal can support. </PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE> - is initialized by <STRONG>start_color</STRONG> to the maximum number of color pairs the + is initialized by <STRONG>start_color</STRONG> to the maximum number of color pairs the terminal can support. Often, its value is the product <STRONG>COLORS</STRONG> x <STRONG>COLORS</STRONG>, but this is not always true. @@ -197,14 +198,14 @@ (respectively defining the maximum number of colors and color pairs the terminal can support). - <STRONG>o</STRONG> It initializes the special color pair <STRONG>0</STRONG> to the default foreground + <STRONG>o</STRONG> It initializes the special color pair <STRONG>0</STRONG> to the default foreground and background colors. No other color pairs are initialized. - <STRONG>o</STRONG> It restores the colors on the terminal to the values they had when + <STRONG>o</STRONG> It restores the colors on the terminal to the values they had when the terminal was just turned on. - <STRONG>o</STRONG> If the terminal supports the <STRONG>initc</STRONG> (<STRONG>initialize_color</STRONG>) capability, - <STRONG>start_color</STRONG> initializes its internal table representing the red, + <STRONG>o</STRONG> If the terminal supports the <STRONG>initc</STRONG> (<STRONG>initialize_color</STRONG>) capability, + <STRONG>start_color</STRONG> initializes its internal table representing the red, green, and blue components of the color palette. The components depend on whether the terminal uses CGA (aka "ANSI") @@ -212,55 +213,65 @@ set). The table is initialized first for eight basic colors (black, red, green, yellow, blue, magenta, cyan, and white), using weights that depend upon the CGA/HLS choice. For "ANSI" colors the - weights are <STRONG>680</STRONG> or <STRONG>0</STRONG> depending on whether the corresponding red, - green, or blue component is used or not. That permits using <STRONG>1000</STRONG> - to represent bold/bright colors. After the initial eight colors - (if the terminal supports more than eight colors) the components - are initialized using the same pattern, but with weights of <STRONG>1000</STRONG>. + weights are <STRONG>680</STRONG> or <STRONG>0</STRONG> depending on whether the corresponding red, + green, or blue component is used or not. That permits using <STRONG>1000</STRONG> + to represent bold/bright colors. After the initial eight colors + (if the terminal supports more than eight colors) the components + are initialized using the same pattern, but with weights of <STRONG>1000</STRONG>. SVr4 uses a similar scheme, but uses <STRONG>1000</STRONG> for the components of the initial eight colors. <STRONG>start_color</STRONG> does not attempt to set the terminal's color palette to - match its built-in table. An application may use <STRONG>init_color</STRONG> to + match its built-in table. An application may use <STRONG>init_color</STRONG> to alter the internal table along with the terminal's color. - These limits apply to color values and color pairs. Values outside + These limits apply to color values and color pairs. Values outside these limits are not valid, and may result in a runtime error: - <STRONG>o</STRONG> <STRONG>COLORS</STRONG> corresponds to the terminal database's <STRONG>max_colors</STRONG> + <STRONG>o</STRONG> <STRONG>COLORS</STRONG> corresponds to the terminal database's <STRONG>max_colors</STRONG> capability, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>). - <STRONG>o</STRONG> color values are expected to be in the range <STRONG>0</STRONG> to <STRONG>COLORS-1</STRONG>, + <STRONG>o</STRONG> color values are expected to be in the range <STRONG>0</STRONG> to <STRONG>COLORS-1</STRONG>, inclusive (including <STRONG>0</STRONG> and <STRONG>COLORS-1</STRONG>). - <STRONG>o</STRONG> a special color value <STRONG>-1</STRONG> is used in certain extended functions to + <STRONG>o</STRONG> a special color value <STRONG>-1</STRONG> is used in certain extended functions to denote the <EM>default</EM> <EM>color</EM> (see <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>). - <STRONG>o</STRONG> <STRONG>COLOR_PAIRS</STRONG> corresponds to the terminal database's <STRONG>max_pairs</STRONG> + <STRONG>o</STRONG> <STRONG>COLOR_PAIRS</STRONG> corresponds to the terminal database's <STRONG>max_pairs</STRONG> capability, (see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>). - <STRONG>o</STRONG> valid color pair values are in the range <STRONG>1</STRONG> to <STRONG>COLOR_PAIRS-1</STRONG>, + <STRONG>o</STRONG> valid color pair values are in the range <STRONG>1</STRONG> to <STRONG>COLOR_PAIRS-1</STRONG>, inclusive. <STRONG>o</STRONG> color pair <STRONG>0</STRONG> is special; it denotes "no color". - Color pair <STRONG>0</STRONG> is assumed to be white on black, but is actually - whatever the terminal implements before color is initialized. It + Color pair <STRONG>0</STRONG> is assumed to be white on black, but is actually + whatever the terminal implements before color is initialized. It cannot be modified by the application. </PRE><H3><a name="h3-has_colors">has_colors</a></H3><PRE> - The <STRONG>has_colors</STRONG> routine requires no arguments. It returns <STRONG>TRUE</STRONG> if the - terminal can manipulate colors; otherwise, it returns <STRONG>FALSE</STRONG>. This - routine facilitates writing terminal-independent programs. For - example, a programmer can use it to decide whether to use color or some - other video attribute. + <STRONG>has_colors</STRONG> returns <STRONG>TRUE</STRONG> if the terminal supports colors and <STRONG>FALSE</STRONG> if it + does not. <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> must be called first, but + <STRONG>start_color</STRONG> need not be. An application might call <STRONG>has_colors</STRONG> to + decide whether to use color or a video attribute like <STRONG>A_BOLD</STRONG> to render + text. + + Color support in <EM>curses</EM> requires that the terminal type description + support the capabilities <STRONG>max_colors</STRONG> (<STRONG>colors</STRONG>), <STRONG>max_pairs</STRONG> (<STRONG>pairs</STRONG>), and + any of + + <STRONG>o</STRONG> <STRONG>set_foreground</STRONG> (<STRONG>setf</STRONG>) and <STRONG>set_background</STRONG> (<STRONG>setb</STRONG>); + + <STRONG>o</STRONG> <STRONG>set_a_foreground</STRONG> (<STRONG>setaf</STRONG>) and <STRONG>set_a_background</STRONG> (<STRONG>setab</STRONG>); or + + <STRONG>o</STRONG> <STRONG>set_color_pair</STRONG> (<STRONG>scp</STRONG>). </PRE><H3><a name="h3-can_change_color">can_change_color</a></H3><PRE> The <STRONG>can_change_color</STRONG> routine requires no arguments. It returns <STRONG>TRUE</STRONG> if - the terminal supports colors and can change their definitions; other, - it returns <STRONG>FALSE</STRONG>. This routine facilitates writing terminal- + the terminal supports colors and can change their definitions; other, + it returns <STRONG>FALSE</STRONG>. This routine facilitates writing terminal- independent programs. @@ -270,19 +281,19 @@ foreground color number, and the background color number. For portable applications: - <STRONG>o</STRONG> The first argument must be a valid color pair value. If default - colors are used (see <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>) the upper limit is - adjusted to allow for extra pairs which use a default color in + <STRONG>o</STRONG> The first argument must be a valid color pair value. If default + colors are used (see <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG>) the upper limit is + adjusted to allow for extra pairs which use a default color in foreground and/or background. <STRONG>o</STRONG> The second and third arguments must be valid color values. - If the color pair was previously initialized, the screen is refreshed - and all occurrences of that color pair are changed to the new + If the color pair was previously initialized, the screen is refreshed + and all occurrences of that color pair are changed to the new definition. - As an extension, <EM>ncurses</EM> allows you to set color pair <STRONG>0</STRONG> via the - <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG> routine, or to specify the use of default + As an extension, <EM>ncurses</EM> allows you to set color pair <STRONG>0</STRONG> via the + <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG> routine, or to specify the use of default colors (color number <STRONG>-1</STRONG>) if you first invoke the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG> routine. @@ -299,22 +310,22 @@ four arguments: the number of the color to be changed followed by three RGB values (for the amounts of red, green, and blue components). - <STRONG>o</STRONG> The first argument must be a valid color value; default colors are - not allowed here. (See the section <STRONG>Colors</STRONG> for the default color + <STRONG>o</STRONG> The first argument must be a valid color value; default colors are + not allowed here. (See the section <STRONG>Colors</STRONG> for the default color index.) - <STRONG>o</STRONG> Each of the last three arguments must be a value in the range <STRONG>0</STRONG> + <STRONG>o</STRONG> Each of the last three arguments must be a value in the range <STRONG>0</STRONG> through <STRONG>1000</STRONG>. - When <STRONG>init_color</STRONG> is used, all occurrences of that color on the screen + When <STRONG>init_color</STRONG> is used, all occurrences of that color on the screen immediately change to the new definition. </PRE><H3><a name="h3-init_extended_color">init_extended_color</a></H3><PRE> - Because <STRONG>init_color</STRONG> uses signed <STRONG>short</STRONG>s for its parameters, that limits - color-values and their red, green, and blue components to 32767 on - modern hardware. The extension <STRONG>init_extended_color</STRONG> uses <STRONG>int</STRONG>s for the - color value and for setting the red, green, and blue components, + Because <STRONG>init_color</STRONG> uses signed <STRONG>short</STRONG>s for its parameters, that limits + color-values and their red, green, and blue components to 32767 on + modern hardware. The extension <STRONG>init_extended_color</STRONG> uses <STRONG>int</STRONG>s for the + color value and for setting the red, green, and blue components, allowing a larger number of colors to be supported. @@ -337,13 +348,13 @@ Because <STRONG>color_content</STRONG> uses signed <STRONG>short</STRONG>s for its parameters, that limits color-values and their red, green, and blue components to 32767 on modern hardware. The extension <STRONG>extended_color_content</STRONG> uses <STRONG>int</STRONG>s for - the color value and for returning the red, green, and blue components, + the color value and for returning the red, green, and blue components, allowing a larger number of colors to be supported. </PRE><H3><a name="h3-pair_content">pair_content</a></H3><PRE> - The <STRONG>pair_content</STRONG> routine allows programmers to find out what colors a - given color pair consists of. It requires three arguments: the color + The <STRONG>pair_content</STRONG> routine allows programmers to find out what colors a + given color pair consists of. It requires three arguments: the color pair number, and two addresses of <STRONG>short</STRONG>s for storing the foreground and the background color numbers. @@ -372,174 +383,177 @@ </PRE><H3><a name="h3-COLOR_PAIR">COLOR_PAIR</a></H3><PRE> <STRONG>COLOR_PAIR(</STRONG><EM>n</EM><STRONG>)</STRONG> converts a color pair number to an attribute. Attributes - can hold color pairs in the range 0 to 255. If you need a color pair - larger than that, you must use functions such as <STRONG>attr_set</STRONG> (which pass - the color pair as a separate parameter) rather than the legacy + can hold color pairs in the range 0 to 255. If you need a color pair + larger than that, you must use functions such as <STRONG>attr_set</STRONG> (which pass + the color pair as a separate parameter) rather than the legacy functions such as <STRONG>attrset</STRONG>. </PRE><H3><a name="h3-PAIR_NUMBER">PAIR_NUMBER</a></H3><PRE> - <STRONG>PAIR_NUMBER(</STRONG><EM>attr</EM>) extracts the color information from its <EM>attr</EM> - parameter and returns it as a color pair number; it is the inverse + <STRONG>PAIR_NUMBER(</STRONG><EM>attr</EM>) extracts the color information from its <EM>attr</EM> + parameter and returns it as a color pair number; it is the inverse operation of <STRONG>COLOR_PAIR</STRONG>. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The routines <STRONG>can_change_color</STRONG> and <STRONG>has_colors</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>. + <STRONG>can_change_color</STRONG> and <STRONG>has_colors</STRONG> return <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>. The other + functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - All other routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4 - specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful - completion. + In <EM>ncurses</EM>, functions returning an <EM>int</EM> recognize several error + conditions. - X/Open defines no error conditions. SVr4 does document some error - conditions which apply in general: + <STRONG>o</STRONG> All return <STRONG>ERR</STRONG> if the screen has not been initialized; see + <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>. - <STRONG>o</STRONG> This implementation will return <STRONG>ERR</STRONG> on attempts to use color values - outside the range <STRONG>0</STRONG> to <STRONG>COLORS</STRONG>-1 (except for the default colors - extension), or use color pairs outside the range <STRONG>0</STRONG> to - <STRONG>COLOR_PAIRS-1</STRONG>. + <STRONG>o</STRONG> All except <STRONG>start_color</STRONG> return <STRONG>ERR</STRONG> if <STRONG>start_color</STRONG> has not been + called, or itself returned <STRONG>ERR</STRONG>. - Color values used in <STRONG>init_color</STRONG> must be in the range <STRONG>0</STRONG> to <STRONG>1000</STRONG>. + <STRONG>o</STRONG> <STRONG>start_color</STRONG> returns <STRONG>ERR</STRONG> if it cannot allocate memory for its color + pair table. - An error is returned from all functions if the terminal has not - been initialized. + <STRONG>o</STRONG> <STRONG>init_color</STRONG> returns <STRONG>ERR</STRONG> if the terminal type does not support + assignable color values; that is, if the <STRONG>initialize_color</STRONG> (<STRONG>initc</STRONG>) + capability is absent from its description. - An error is returned from secondary functions such as <STRONG>init_pair</STRONG> if - <STRONG>start_color</STRONG> was not called. + <STRONG>o</STRONG> <STRONG>init_color</STRONG> returns <STRONG>ERR</STRONG> if any of its <EM>r</EM>, <EM>g</EM>, <EM>b</EM> arguments is outside + the range 0-1000 inclusive. - <STRONG>o</STRONG> SVr4 does much the same, except that it returns <STRONG>ERR</STRONG> from - <STRONG>pair_content</STRONG> if the pair was not initialized using <STRONG>init_pairs</STRONG> and - it returns <STRONG>ERR</STRONG> from <STRONG>color_content</STRONG> if the terminal does not support - changing colors. + <STRONG>o</STRONG> <STRONG>init_pair</STRONG>, <STRONG>init_color</STRONG>, <STRONG>init_extended_pair</STRONG>, <STRONG>init_extended_color</STRONG>, + <STRONG>color_content</STRONG>, <STRONG>pair_content</STRONG>, <STRONG>extended_color_content</STRONG>, and + <STRONG>extended_pair_content</STRONG> return <STRONG>ERR</STRONG> on attempts to use - This implementation does not return <STRONG>ERR</STRONG> for either case. + <STRONG>o</STRONG> color identifiers outside the range 0-<STRONG>COLORS</STRONG>-1 inclusive, the + default colors extension notwithstanding, or - Specific functions make additional checks: + <STRONG>o</STRONG> color pair identifiers outside the range 0-<STRONG>COLOR_PAIRS</STRONG>-1 + inclusive. - <STRONG>init_color</STRONG> - returns an error if the terminal does not support this feature, - e.g., if the <STRONG>initialize_color</STRONG> capability is absent from the - terminal description. - <STRONG>start_color</STRONG> - returns an error if the color table cannot be allocated. +</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> + In <EM>ncurses</EM>, <STRONG>init_pair</STRONG> accepts negative foreground and background color + arguments to support its <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG> extension, but only + after the latter function has been called. + The assumption that <STRONG>COLOR_BLACK</STRONG> is the terminal's default background + color can be overridden using <EM>ncurses</EM>'s <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG> + extension. -</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - In the <EM>ncurses</EM> implementation, there is a separate color activation - flag, color palette, color pairs table, and associated <STRONG>COLORS</STRONG> and - <STRONG>COLOR_PAIRS</STRONG> counts for each screen; the <STRONG>start_color</STRONG> function only - affects the current screen. The SVr4/XSI interface is not really - designed with this in mind, and historical implementations may use a - single shared color palette. - - Setting an implicit background color via a color pair affects only - character cells that a character write operation explicitly touches. - To change the background color used when parts of a window are blanked + In <EM>ncurses</EM>, each pointer passed to <STRONG>color_content</STRONG> and <STRONG>pair_content</STRONG> can + be null, in which case the library ignores it, permitting the + application to disregard unnecessary information. + + In <EM>ncurses</EM>, each screen has a color activation flag, color palette, + color pair table, and associated <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG> values; + <STRONG>start_color</STRONG> affects only the current screen. The SVr4 and X/Open + Curses interface was not really designed with this in mind; historical + implementations may use a single shared color palette. + + Setting an implicit background color via a color pair affects only + character cells that a character write operation explicitly touches. + To change the background color used when parts of a window are blanked by erasing or scrolling operations, see <STRONG><A HREF="curs_bkgd.3x.html">curs_bkgd(3x)</A></STRONG>. - Several caveats apply on older x86 machines (e.g., i386, i486) with - VGA-compatible graphics: + Several caveats apply to IBM PC-compatible machines of the 80486 era + and earlier with CGA/EGA/VGA video. - <STRONG>o</STRONG> COLOR_YELLOW is actually brown. To get yellow, use COLOR_YELLOW - combined with the <STRONG>A_BOLD</STRONG> attribute. + <STRONG>o</STRONG> <STRONG>COLOR_YELLOW</STRONG> was frequently converted, in the analog domain, to a + shade of brown if the intensity bit was not set. To get yellow on + such devices, one would combine <STRONG>COLOR_YELLOW</STRONG> with the <STRONG>A_BOLD</STRONG> + attribute. - <STRONG>o</STRONG> The A_BLINK attribute should in theory cause the background to go - bright. This often fails to work, and even some cards for which it - mostly works (such as the Paradise and compatibles) do the wrong - thing when you try to set a bright "yellow" background (you get a - blinking yellow foreground instead). + <STRONG>o</STRONG> The <STRONG>A_BLINK</STRONG> attribute should in theory make the background bright. + This often fails to work, and even VGA controllers for which it + mostly works, such as those from Paradise and compatibles, do the + wrong thing when you try to set a bright "yellow" background -- you + get a blinking yellow foreground instead. - <STRONG>o</STRONG> Color RGB values are not settable. + <STRONG>o</STRONG> Color RGB values are not configurable on these devices (in text + mode). </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - The functions marked as extensions were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and - are not found in SVr4 <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous - curses implementation. + The functions marked as extensions originated in <EM>ncurses</EM>, and are not + found in SVr4 <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> + implementation. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> Applications employing <EM>ncurses</EM> extensions should condition their use on the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. - This implementation satisfies X/Open Curses's minimum maximums for - <STRONG>COLORS</STRONG> and <STRONG>COLOR_PAIRS</STRONG>. - - The <STRONG>init_pair</STRONG> routine accepts negative values of foreground and - background color to support the <STRONG><A HREF="default_colors.3x.html">use_default_colors(3x)</A></STRONG> extension, but - only if that routine has been first invoked. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - The assumption that <STRONG>COLOR_BLACK</STRONG> is the default background color for all - terminals can be modified using the <STRONG><A HREF="default_colors.3x.html">assume_default_colors(3x)</A></STRONG> - extension. - - This implementation checks the pointers, e.g., for the values returned - by <STRONG>color_content</STRONG> and <STRONG>pair_content</STRONG>, and will treat those as optional - parameters when null. + <EM>ncurses</EM> satisfies X/Open Curses's minimum maximums for <EM>COLORS</EM> and + <EM>COLOR</EM><STRONG>_</STRONG><EM>PAIRS</EM>. X/Open Curses does not specify a limit for the number of colors and - color pairs which a terminal can support. However, in its use of <STRONG>short</STRONG> - for the parameters, it carries over SVr4's implementation detail for - the compiled terminfo database, which uses signed 16-bit numbers. This - implementation provides extended versions of those functions which use - <STRONG>short</STRONG> parameters, allowing applications to use larger color- and pair- - numbers. + color pairs which a terminal can support. However, in its use of <EM>short</EM> + for the parameters, it carries over SVr4's implementation detail for + the compiled <EM>terminfo</EM> database, which uses signed 16-bit numbers. + <EM>ncurses</EM> provides extended versions of the functions using <EM>short</EM> + parameters, allowing applications to use larger color and pair + identifiers. - The <STRONG>reset_color_pairs</STRONG> function is an extension of <EM>ncurses</EM>. + SVr4 <EM>curses</EM> returns <EM>ERR</EM> from <EM>pair</EM><STRONG>_</STRONG><EM>content</EM> if its <EM>pair</EM> argument was not + initialized using <EM>init</EM><STRONG>_</STRONG><EM>pairs</EM>, and from <EM>color</EM><STRONG>_</STRONG><EM>content</EM> if the terminal + does not support changing colors. <EM>ncurses</EM> does neither. </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - SVr3.2 introduced color support to curses in 1987. - - SVr4 made internal changes, e.g., moving the storage for the color - state from <STRONG>SP</STRONG> (the <EM>SCREEN</EM> structure) to <STRONG>cur_term</STRONG> (the <EM>TERMINAL</EM> - structure), but provided the same set of library functions. - - SVr4 curses limits the number of color pairs to 64, reserving color - pair zero (0) as the terminal's initial uncolored state. This limit - arises because the color pair information is a bitfield in the <STRONG>chtype</STRONG> - data type (denoted by <STRONG>A_COLOR</STRONG>). - - Other implementations of curses had different limits: - - <STRONG>o</STRONG> PCCurses (1987-1990) provided for only eight (8) colors. - - <STRONG>o</STRONG> PDCurses (1992-present) inherited the 8-color limitation from - PCCurses, but changed this to 256 in version 2.5 (2001), along with - changing <STRONG>chtype</STRONG> from 16-bits to 32-bits. - - <STRONG>o</STRONG> X/Open Curses (1992-present) added a new structure <STRONG>cchar_t</STRONG> to store - the character, attributes and color pair values, allowing increased - range of color pairs. Both color pairs and color-values used a - signed <STRONG>short</STRONG>, limiting values to 15 bits. - - <STRONG>o</STRONG> <EM>ncurses</EM> (1992-present) uses eight bits for <STRONG>A_COLOR</STRONG> in <STRONG>chtype</STRONG> - values. - - Version 5.3 provided a wide-character interface (2002), but left - color pairs as part of the attributes-field. - - Since version 6 (2015), ncurses uses a separate <STRONG>int</STRONG> for color pairs - in the <STRONG>cchar_t</STRONG> values. When those color pair values fit in 8 bits, - ncurses allows color pairs to be manipulated via the functions - using <STRONG>chtype</STRONG> values. - - <STRONG>o</STRONG> NetBSD curses used 6 bits from 2000 (when colors were first - supported) until 2004. At that point, NetBSD changed to use 10 - bits. As of 2021, that size is unchanged. Like <EM>ncurses</EM> before - version 6, the NetBSD color pair information is stored in the - attributes field of <STRONG>cchar_t</STRONG>, limiting the number of color pairs by - the size of the bitfield. + SVr3.2 (1987) introduced color support to <EM>curses</EM> with all of the + symbols in the synopsis above except those marked as extensions. It + reserved color pair 0 as the terminal's initial, "uncolored" state, and + limited the number of possible color pairs to 64, because the color + pair datum was encoded in six bits of a <EM>chtype</EM>. + + SVr4 made only internal changes, such as moving the storage of color + state from the <EM>SCREEN</EM> structure (pointed to by <EM>SP</EM>) to the <EM>TERMINAL</EM> + structure (pointed to by <EM>cur</EM><STRONG>_</STRONG><EM>term</EM>). + + Other <EM>curses</EM> implementations impose different limits on the number of + colors and color pairs. + + <STRONG>o</STRONG> <EM>PCCurses</EM> (1987-1990) provided for only 8 colors (and therefore + required at most 8x8 = 64 color pairs). + + <STRONG>o</STRONG> <EM>PDCurses</EM> (1992-present) inherited the 8-color limitation from + <EM>PCCurses</EM>, but changed this to 256 in version 2.5 (2001), and + widened its <EM>chtype</EM> from 16 to 32 bits. + + <STRONG>o</STRONG> X/Open Curses (1992-present) specified a new structure type, + <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>, to store the character code, attribute flags, and color + pair identifier, allowing an increased range of color pairs. It + specifies a <EM>short</EM> as storing identifiers for colors and color + pairs, limiting portable values to 15 bits; negative values are + invalid in System V. + + <STRONG>o</STRONG> <EM>ncurses</EM> (1992-present), in its non-wide-character configuration, + uses 8 bits of <EM>chtype</EM> for the color pair identifier. + + Version 5.3 (2002) offered a wide-character interface, but encoded + the color pair identifier with attributes in the character type. + + Since version 6 (2015), <EM>ncurses</EM> uses a separate <EM>int</EM> for the color + pair identifier in a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>, introducing extension functions to + manage the wider type. When a color pair value fits in 8 bits, + <EM>ncurses</EM> permits color pair data to be manipulated via the functions + taking <EM>chtype</EM> arguments, even when a <EM>curses</EM> window uses wide- + character cells. + + <STRONG>o</STRONG> NetBSD <EM>curses</EM> used 6 bits for the color pair identifier from 2000 + (when it first added color support) until 2004. At that point, + NetBSD widened the color pair identifier to use 9 bits. As of + 2025, that size is unchanged. Like <EM>ncurses</EM> before version 6, the + NetBSD color pair datum is stored in the attributes field of + <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>, limiting the number of color pairs. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> +ncurses 6.6 2025-08-23 <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_delch.3x.html b/doc/html/man/curs_delch.3x.html index ca638df7ce2e..7e268828c2d8 100644 --- a/doc/html/man/curs_delch.3x.html +++ b/doc/html/man/curs_delch.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2006,2010 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_delch.3x,v 1.34 2024/04/20 19:24:14 tom Exp @ + * @Id: curs_delch.3x,v 1.49 2025/04/05 21:59:53 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_delch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_delch 3x 2025-04-05 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_delch 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_delch 3x 2025-04-05 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>delch</STRONG>, <STRONG>wdelch</STRONG>, <STRONG>mvdelch</STRONG>, <STRONG>mvwdelch</STRONG> - delete a character from a <EM>curses</EM> window @@ -55,51 +53,58 @@ <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> <STRONG>int</STRONG> <STRONG>delch(void);</STRONG> - <STRONG>int</STRONG> <STRONG>wdelch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wdelch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>mvdelch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwdelch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwdelch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - <STRONG>wdelch</STRONG> deletes the character at the cursor position in <EM>win</EM>. - <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function. - - <STRONG>wdelch</STRONG> moves all characters to the right of the cursor on the same line - to the left one position and replaces the contents of the rightmost - position on the line with the window's blank character; see <STRONG><A HREF="curs_bkgd.3x.html">bkgd(3x)</A></STRONG> - (wide-character API users may consult <STRONG><A HREF="curs_bkgrnd.3x.html">bkgrnd(3x)</A></STRONG> instead). The cursor - position does not change (after moving to (<EM>y</EM>, <EM>x</EM>), if specified). + <STRONG>wdelch</STRONG> deletes the character at the cursor position in <EM>win</EM>. It moves + all characters to the right of the cursor on the same line to the left + one position and replaces the contents of the rightmost position on the + line with the window's background character; see <STRONG><A HREF="curs_bkgd.3x.html">bkgd(3x)</A></STRONG> (wide- + character API users: <STRONG><A HREF="curs_bkgrnd.3x.html">bkgrnd(3x)</A></STRONG>). The cursor position does not change + (after moving to (<EM>y</EM>, <EM>x</EM>), if specified). <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the + variants of this function. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - Functions taking a <EM>WINDOW</EM> pointer argument fail if the pointer is <STRONG>NULL</STRONG>. + In <EM>ncurses</EM>, these functions fail if + + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, or + + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer. - Functions prefixed with "mv" first perform cursor movement and fail if + Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> <STRONG>delch</STRONG>, <STRONG>mvdelch</STRONG>, and <STRONG>mvwdelch</STRONG> may be implemented as macros. - A terminal's <STRONG>delete_character</STRONG> (<STRONG>dch1</STRONG>) capability is not necessarily + A terminal's <STRONG>delete_character</STRONG> (<STRONG>dch1</STRONG>) capability is not necessarily employed. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - SVr4 <EM>curses</EM> describes a successful return value only as "an integer - value other than <STRONG>ERR</STRONG>". + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr2 (1984) introduced <EM>wdelch</EM>. +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG> +ncurses 6.6 2025-04-05 <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -109,6 +114,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF= <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_deleteln.3x.html b/doc/html/man/curs_deleteln.3x.html index c9c500146182..58b20ea7ecd9 100644 --- a/doc/html/man/curs_deleteln.3x.html +++ b/doc/html/man/curs_deleteln.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2007,2010 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,27 +27,25 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_deleteln.3x,v 1.38 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_deleteln.3x,v 1.55 2025/07/05 12:46:36 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_deleteln 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_deleteln 3x 2025-07-05 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_deleteln 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_deleteln 3x 2025-07-05 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>deleteln</STRONG>, <STRONG>wdeleteln</STRONG>, <STRONG>insdelln</STRONG>, <STRONG>winsdelln</STRONG>, <STRONG>insertln</STRONG>, <STRONG>winsertln</STRONG> - delete + <STRONG>deleteln</STRONG>, <STRONG>wdeleteln</STRONG>, <STRONG>insertln</STRONG>, <STRONG>winsertln</STRONG>, <STRONG>insdelln</STRONG>, <STRONG>winsdelln</STRONG> - delete or insert lines in a <EM>curses</EM> window @@ -55,61 +53,63 @@ <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> <STRONG>int</STRONG> <STRONG>deleteln(void);</STRONG> - <STRONG>int</STRONG> <STRONG>wdeleteln(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>insdelln(int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>winsdelln(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wdeleteln(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>insertln(void);</STRONG> - <STRONG>int</STRONG> <STRONG>winsertln(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>winsertln(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>insdelln(int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>winsdelln(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The <STRONG>deleteln</STRONG> and <STRONG>wdeleteln</STRONG> routines delete the line under the cursor in - the window; all lines below the current line are moved up one line. - The bottom line of the window is cleared. The cursor position does not - change. + <STRONG>wdeleteln</STRONG> deletes the line at the cursor in <EM>win</EM>; all lines below it + move up one line. <EM>curses</EM> then fills the bottom line of <EM>win</EM> with the + background character configured by <STRONG><A HREF="curs_bkgd.3x.html">wbkgdset(3x)</A></STRONG> (wide-character API + users: <STRONG><A HREF="curs_bkgrnd.3x.html">wbkgrndset(3x)</A></STRONG>). The cursor position does not change. - The <STRONG>insdelln</STRONG> and <STRONG>winsdelln</STRONG> routines, for positive <EM>n</EM>, insert <EM>n</EM> lines - into the specified window above the current line. The <EM>n</EM> bottom lines - are lost. For negative <EM>n</EM>, delete <EM>n</EM> lines (starting with the one under - the cursor), and move the remaining lines up. The bottom <EM>n</EM> lines are - cleared. The current cursor position remains the same. + <STRONG>winsertln</STRONG> inserts a new, empty line of characters above the line at the + cursor in <EM>win</EM>, shifting the existing lines down by one. The content of + the window's bottom line is lost; <EM>curses</EM> fills the new line with the + background character. The cursor position does not change. - The <STRONG>insertln</STRONG> and <STRONG>winsertln</STRONG> routines insert a blank line above the - current line and the bottom line is lost. + <STRONG>winsdelln</STRONG> inserts or deletes <EM>n</EM> lines in <EM>win</EM> as <EM>n</EM> is positive or + negative, respectively, as if by repeatedly calling <STRONG>winsertln</STRONG> or + <STRONG>wdeleteln</STRONG>. <STRONG>winsdelln(</STRONG>...<STRONG>,</STRONG> <STRONG>0)</STRONG> performs no operation. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - These routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4 - specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful - completion. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - X/Open defines no error conditions. In this implementation, if the - window parameter is null, an error is returned. + In <EM>ncurses</EM>, they fail if <EM>win</EM> is <EM>NULL</EM>. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that all but <STRONG>winsdelln</STRONG> may be macros. + All of these functions except <STRONG>winsdelln</STRONG> may be implemented as macros. - These routines do not require a hardware line delete or insert feature - in the terminal. In fact, they will not use hardware line - delete/insert unless <STRONG>idlok(...,</STRONG> <STRONG>TRUE)</STRONG> has been set on the current - window. + These functions do not require the terminal to possess hardware line + deletion or insertion capabilities. Even if available, by default + <EM>curses</EM> does not use them; see <STRONG><A HREF="idlok.3x.html">idlok(3x)</A></STRONG>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. The standard - specifies that they return <STRONG>ERR</STRONG> on failure, but specifies no error - conditions. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced <EM>deleteln</EM>, <EM>wdeleteln</EM>, <EM>insertln</EM>, and <EM>winsertln</EM>. + + SVr3.1 (1987) added <EM>insdelln</EM> and <EM>winsdelln</EM>. -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG> +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> + +ncurses 6.6 2025-07-05 <STRONG><A HREF="curs_deleteln.3x.html">curs_deleteln(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -119,6 +119,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="cu <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_extend.3x.html b/doc/html/man/curs_extend.3x.html index e8b3a4682f73..9c163a0901a3 100644 --- a/doc/html/man/curs_extend.3x.html +++ b/doc/html/man/curs_extend.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1999-2010,2016 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,88 +28,94 @@ * authorization. * **************************************************************************** * Author: Thomas E. Dickey 1999-on - * @Id: curs_extend.3x,v 1.46 2024/03/16 15:35:01 tom Exp @ + * @Id: curs_extend.3x,v 1.67 2025/11/12 00:46:51 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_extend 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_extend 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_extend 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_extend 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>curses_version</STRONG>, <STRONG>use_extended_names</STRONG> - miscellaneous <EM>curses</EM> extensions + <STRONG>curses_version</STRONG>, <STRONG>use_extended_names</STRONG> - miscellaneous <EM>ncurses</EM> extensions </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>curses_version(void);</STRONG> - <STRONG>int</STRONG> <STRONG>use_extended_names(bool</STRONG> <EM>enable</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>use_extended_names(bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These functions are extensions to the curses library which do not fit - easily into other categories. + These <EM>ncurses</EM> extensions to the <EM>curses</EM> library do not fit easily into + other functional categories. </PRE><H3><a name="h3-curses_version">curses_version</a></H3><PRE> - Use <STRONG>curses_version</STRONG> to get the version number, including patch level of - the library, prefixed by "ncurses", e.g., - - <STRONG>ncurses</STRONG> <STRONG>5.0.19991023</STRONG> + <STRONG>curses_version</STRONG> returns a pointer to a string containing the library's + name and version number, including its patch level, for example + "ncurses 6.5.20240720". </PRE><H3><a name="h3-use_extended_names">use_extended_names</a></H3><PRE> - The <STRONG>use_extended_names</STRONG> function controls whether the calling - application is able to use user-defined or nonstandard names which may - be compiled into the terminfo description, i.e., via the terminfo or - termcap interfaces. Normally these names are available for use, since - the essential decision is made by using the <STRONG>-x</STRONG> option of <STRONG>tic</STRONG> to compile - extended terminal definitions. However you can disable this feature to - ensure compatibility with other implementations of curses. + <STRONG>use_extended_names</STRONG> configures whether the library recognizes user- + defined or nonstandard <EM>terminfo</EM> capability names that may be compiled + into terminal type descriptions via the <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> or + <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG> interfaces. Normally these names are available for + use, since the essential decision is made through use of <STRONG><A HREF="tic.1m.html">tic(1)</A></STRONG>'s <STRONG>-x</STRONG> + option to include such extensions in terminal type descriptions. + <STRONG>use_extended_names(FALSE)</STRONG> prevents <EM>ncurses</EM> from recognizing these + capabilities to ensure compatibility with other implementations of + <EM>curses</EM>. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - <STRONG>curses_version</STRONG> returns a pointer to static memory; you should not free - this in your application. + <STRONG>curses_version</STRONG> returns a constant string. + + <STRONG>use_extended_names</STRONG> returns the previous state of extended capability + name recognition, allowing you to save this property and restore it. - <STRONG>use_extended_names</STRONG> returns the previous state, allowing you to save - this and restore it. + +</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> + The pointer returned by <STRONG>curses_version</STRONG> corresponds to statically + allocated memory; do not attempt to <STRONG>free(3)</STRONG> it. </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - These functions are <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> extensions, and are not found in SVr4 - <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous curses implementation. + These functions are <EM>ncurses</EM> extensions, and are not found in SVr4 + <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> implementation. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> Applications employing <EM>ncurses</EM> extensions should condition their use on the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + NetBSD 9 added a <EM>curses</EM><STRONG>_</STRONG><EM>version</EM> function that intentionally returns a + string devoid of version information. + </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> - Thomas Dickey. + Thomas Dickey </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>, <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>, <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>, <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, - <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>, <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG>, <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>, - <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>, <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> - + <EM>ncurses</EM> offers several other extensions to the X/Open Curses API. + <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>, <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>, + <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>, <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG>, + <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>, <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG>, <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>, <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> -ncurses 6.5 2024-03-16 <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -122,6 +128,7 @@ ncurses 6.5 2024-03-16 <STRONG><A HREF=" </ul> </li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> +<li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-AUTHORS">AUTHORS</a></li> diff --git a/doc/html/man/curs_get_wch.3x.html b/doc/html/man/curs_get_wch.3x.html index 291ef67f1c0a..317e52e492a5 100644 --- a/doc/html/man/curs_get_wch.3x.html +++ b/doc/html/man/curs_get_wch.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2002-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,37 +27,35 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_get_wch.3x,v 1.40 2024/04/20 19:23:03 tom Exp @ + * @Id: curs_get_wch.3x,v 1.71 2025/08/16 19:11:47 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_get_wch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_get_wch 3x 2025-08-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_get_wch 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_get_wch 3x 2025-08-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>get_wch</STRONG>, <STRONG>wget_wch</STRONG>, <STRONG>mvget_wch</STRONG>, <STRONG>mvwget_wch</STRONG>, <STRONG>unget_wch</STRONG> - get (or push - back) a wide character from <EM>curses</EM> terminal keyboard + back) a wide character from <EM>curses</EM> terminal keyboard buffer </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>get_wch(wint_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wget_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvget_wch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwget_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>get_wch(wint_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wget_wch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvget_wch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwget_wch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>unget_wch(const</STRONG> <STRONG>wchar_t</STRONG> <EM>wc</EM><STRONG>);</STRONG> @@ -65,65 +63,80 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> </PRE><H3><a name="h3-Reading-Characters">Reading Characters</a></H3><PRE> - <STRONG>wget_wch</STRONG> gathers a key stroke <EM>wch</EM> from the terminal keyboard associated - with a <EM>curses</EM> window <EM>win</EM>, returning <STRONG>OK</STRONG> if a wide character is read, - <STRONG>KEY_CODE_YES</STRONG> if a function key is read, and <STRONG>ERR</STRONG> if no key event is + <STRONG>wget_wch</STRONG> gathers a key event from the terminal keyboard associated with + a <EM>curses</EM> window <EM>win</EM>, returning <STRONG>OK</STRONG> if a wide character is read, + <STRONG>KEY_CODE_YES</STRONG> if a function key is read, and <STRONG>ERR</STRONG> if no key event is available. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function. - When input is pending, <STRONG>wget_wch</STRONG> stores an integer identifying the key - stroke in <EM>wch</EM>; for alphanumeric and punctuation keys, this value + When input is pending, <STRONG>wget_wch</STRONG> stores an integer identifying the key + event in <EM>wch</EM>; for alphanumeric and punctuation keys, this value corresponds to the character encoding used by the terminal. Use of the - control key as a modifier often results in a distinct code. The - behavior of other keys depends on whether <EM>win</EM> is in keypad mode; see - subsections "Keypad Mode" and "Predefined Key Codes" in <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>. + control key as a modifier, by holding it down while pressing and + releasing another key, often results in a distinct code. The behavior + of other keys depends on whether <EM>win</EM> is in keypad mode; see subsections + "Keypad Mode" and "Key Codes" in <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>. If no input is pending, then if the no-delay flag is set in the window (see <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>), the function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits - until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> has been called, this - happens after one character is read. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> has been called, - it occurs when the next newline is read. If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been - called, <EM>curses</EM> waits until a character is typed or the specified delay - elapses. + until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> or <STRONG><A HREF="curs_inopts.3x.html">raw(3x)</A></STRONG> has been + called, this happens after one character is read. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> or + <STRONG><A HREF="curs_inopts.3x.html">noraw(3x)</A></STRONG> has been called, it occurs when the next newline is read. + (Because the terminal's canonical or "cooked" mode is line-buffered, + multiple <STRONG>wget_wch</STRONG> calls may then be necessary to empty the input + queue.) If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been called, <EM>curses</EM> waits until input is + available or the specified delay elapses. If <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> has been called, and the window is not a pad, <EM>curses</EM> writes - <EM>wch</EM> to the window (at the cursor position) per the following rules. + the wide character from the input queue to the window (at the cursor + position) per the following rules. - <STRONG>o</STRONG> If <EM>wch</EM> matches the terminal's erase character, the cursor moves - leftward one position and the new position is erased as if - <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and then <STRONG><A HREF="curs_delch.3x.html">wdelch(3x)</A></STRONG> were called. When the window's - keypad mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are - handled the same way. + <STRONG>o</STRONG> If the wide character matches the terminal's erase character (see + <STRONG><A HREF="curs_termattrs.3x.html">erasewchar(3x)</A></STRONG>), the cursor moves leftward one position and the new + position is erased as if <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and then <STRONG><A HREF="curs_delch.3x.html">wdelch(3x)</A></STRONG> were called. + When the window's keypad mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and + <STRONG>KEY_BACKSPACE</STRONG> are handled the same way. - <STRONG>o</STRONG> <EM>curses</EM> writes any other <EM>wch</EM> to the window, as with <STRONG><A HREF="curs_add_wch.3x.html">wecho_wchar(3x)</A></STRONG>. + <STRONG>o</STRONG> <EM>curses</EM> writes any other wide character to the window, as with + <STRONG><A HREF="curs_add_wch.3x.html">wecho_wchar(3x)</A></STRONG>. - <STRONG>o</STRONG> If the window has been moved or modified since the last call to - <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG>. + <STRONG>o</STRONG> If the window <EM>win</EM> has been moved or modified since the last call to + <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG> on it. - If <EM>wch</EM> is a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> stores - the the character code for newline (line feed) in <EM>wch</EM> instead. + If the wide character is a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, + <STRONG>wget_wch</STRONG> stores the wide character code for line feed in <EM>wch</EM> instead. </PRE><H3><a name="h3-Ungetting-Characters">Ungetting Characters</a></H3><PRE> - <STRONG>unget_wch</STRONG> places <EM>wch</EM> into the input queue to be returned by the next - call to <STRONG>wget_wch</STRONG>. A single input queue serves all windows. + <STRONG>unget_wch</STRONG> places <EM>wc</EM> into the input queue to be retrieved by the next + call to <STRONG>wget_wch</STRONG>. A single input queue serves all windows associated + with the screen. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - <STRONG>wget_wch</STRONG> returns <STRONG>OK</STRONG> when it reads a wide character and <STRONG>KEY_CODE_YES</STRONG> - when it reads a function key code. It returns <STRONG>ERR</STRONG> if + <STRONG>wget_wch</STRONG> returns <STRONG>OK</STRONG> when it reads a wide character, <STRONG>KEY_CODE_YES</STRONG> when + it reads a function key code, and <STRONG>ERR</STRONG> on failure. <STRONG>wget_wch</STRONG> fails if + its timeout expires without any data arriving, which cannot happen if + <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG> is in effect on the window. + + In <EM>ncurses</EM>, <STRONG>wget_wch</STRONG> also fails if - <STRONG>o</STRONG> the <EM>WINDOW</EM> pointer is <STRONG>NULL</STRONG>, or + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> its timeout expires without any data arriving, or + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, or - <STRONG>o</STRONG> execution was interrupted by a signal, in which case <STRONG>errno</STRONG> is set - to <STRONG>EINTR</STRONG>. + <STRONG>o</STRONG> execution was interrupted by a signal, in which case <EM>errno</EM> is set + to <EM>EINTR</EM>. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. - <STRONG>unget_wch</STRONG> returns <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> if there is no more room in the - input queue. + <STRONG>unget_wch</STRONG> returns <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. In <EM>ncurses</EM>, + <STRONG>unget_wch</STRONG> fails if + + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, or + + <STRONG>o</STRONG> there is no more room in the input queue. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> @@ -132,15 +145,13 @@ All of these functions except <STRONG>wget_wch</STRONG> and <STRONG>unget_wch</STRONG> may be implemented as macros. - Unlike <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>, <STRONG>wget_wch</STRONG> and its variants store the value of the - input character in an additional <EM>wch</EM> parameter instead of the return - value. + Unlike <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>, <STRONG>wget_wch</STRONG> stores the value of the input character in + an additional <EM>wch</EM> parameter instead of the return value. - Unlike <STRONG>ungetch</STRONG>, <STRONG>unget_wch</STRONG> cannot distinguish function key codes - <STRONG>wget_wch</STRONG> from conventional character codes. An application can - overcome this limitation by pushing function key codes with <STRONG>ungetch</STRONG> and - subsequently checking the return value of <STRONG>wget_wch</STRONG> for a match with - <STRONG>KEY_CODE_YES</STRONG>. + Unlike <STRONG>ungetch</STRONG>, <STRONG>unget_wch</STRONG> cannot distinguish function key codes from + conventional character codes. An application can overcome this + limitation by pushing function key codes with <STRONG>ungetch</STRONG> and subsequently + checking the return value of <STRONG>wget_wch</STRONG> for a match with <STRONG>KEY_CODE_YES</STRONG>. </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> @@ -151,23 +162,32 @@ Applications employing <EM>ncurses</EM> extensions should condition their use on the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. - X/Open Curses, Issue 4 describes these functions. It specifies no - error conditions for them. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - See the "PORTABILITY" section of <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> regarding the interaction - of <STRONG>wget_wch</STRONG> with signal handlers. + See the "PORTABILITY" section of <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> regarding the interaction + of <EM>wget</EM><STRONG>_</STRONG><EM>wch</EM> with signal handlers. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + X/Open Curses Issue 4 (1995) initially specified these functions. The + System V Interface Definition Version 4 of the same year specified + functions named <EM>wgetwch</EM> (with its variants) <EM>ungetwch</EM>. These were later + additions to SVr4.<EM>x</EM>, not appearing in the first SVr4 (1989). They + differ from X/Open's later <EM>wget</EM><STRONG>_</STRONG><EM>wch</EM> and <EM>unget</EM><STRONG>_</STRONG><EM>wch</EM> in that <EM>wgetwch</EM> takes + no <EM>wch</EM> argument, but returns the (wide) key code as an <EM>int</EM> (with no + provision for distinguishing a character code from a function key + code); and <EM>ungetwch</EM> takes a non-<EM>const</EM> <EM>int</EM> argument. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in its non-wide-character configuration. - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> +ncurses 6.6 2025-08-16 <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -183,6 +203,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="c <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_get_wstr.3x.html b/doc/html/man/curs_get_wstr.3x.html index 9e18e64f3dae..e828cf3c5d00 100644 --- a/doc/html/man/curs_get_wstr.3x.html +++ b/doc/html/man/curs_get_wstr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2002-2012,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,158 +27,203 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_get_wstr.3x,v 1.48 2024/04/20 19:18:18 tom Exp @ + * @Id: curs_get_wstr.3x,v 1.79 2025/10/21 00:08:50 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_get_wstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_get_wstr 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_get_wstr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_get_wstr 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>get_wstr</STRONG>, <STRONG>getn_wstr</STRONG>, <STRONG>wget_wstr</STRONG>, <STRONG>wgetn_wstr</STRONG>, <STRONG>mvget_wstr</STRONG>, <STRONG>mvgetn_wstr</STRONG>, - <STRONG>mvwget_wstr</STRONG>, <STRONG>mvwgetn_wstr</STRONG> - get a wide-character string from a <EM>curses</EM> + <STRONG>mvwget_wstr</STRONG>, <STRONG>mvwgetn_wstr</STRONG> - read a wide-character string from a <EM>curses</EM> terminal keyboard </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>get_wstr(wint_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>getn_wstr(wint_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wget_wstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wgetn_wstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>get_wstr(wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wget_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvget_wstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwget_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvget_wstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvgetn_wstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwget_wstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwgetn_wstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>getn_wstr(wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wgetn_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvgetn_wstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwgetn_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wint_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The function <STRONG>wgetn_wstr</STRONG> is equivalent to a series of calls to - <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG> until a newline or carriage return terminates the series: + <STRONG>wget_wstr</STRONG> populates a user-supplied wide-character string buffer <EM>wstr</EM> + by repeatedly calling <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG> with the <EM>win</EM> argument until a line + feed or carriage return character is input. The function - <STRONG>o</STRONG> The terminating character is not included in the returned string. + <STRONG>o</STRONG> does not copy the terminating character to <EM>wstr</EM>; - <STRONG>o</STRONG> An end-of-file condition is represented by <STRONG>WEOF</STRONG>, as defined in - <STRONG><wchar.h></STRONG>. + <STRONG>o</STRONG> populates <EM>wstr</EM> with <EM>WEOF</EM> (as defined in <EM>wchar.h</EM>) if an end-of-file + condition occurs on the input; - <STRONG>o</STRONG> In all instances, the end of the string is terminated by a null - <STRONG>wchar_t</STRONG>. + <STRONG>o</STRONG> always terminates the string with a null wide character (after any + <EM>WEOF</EM>); - <STRONG>o</STRONG> The function stores the result in the area pointed to by the <EM>wstr</EM> - parameter. + <STRONG>o</STRONG> interprets the screen's wide erase and wide kill characters (see + <STRONG><A HREF="curs_termattrs.3x.html">erasewchar(3x)</A></STRONG> and <STRONG><A HREF="curs_termattrs.3x.html">killwchar(3x)</A></STRONG>); - <STRONG>o</STRONG> The function reads at most <EM>n</EM> characters, thus preventing a possible - overflow of the input buffer. + <STRONG>o</STRONG> recognizes function keys only if the screen's keypad option is + enabled (see <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG>); - Any attempt to enter more characters (other than the terminating - newline or carriage return) causes a beep. + <STRONG>o</STRONG> treats the function keys <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> the same as the + wide erase character; and - Function keys also cause a beep and are ignored. + <STRONG>o</STRONG> discards function key inputs other than those treated as the wide + erase or wide kill characters, calling <STRONG><A HREF="curs_beep.3x.html">beep(3x)</A></STRONG>. - The user's <EM>erase</EM> and <EM>kill</EM> characters are interpreted: + The wide erase character replaces the character at the end of the + buffer with a null wide character, while the wide kill character does + the same for the entire buffer. - <STRONG>o</STRONG> The <EM>erase</EM> character (e.g., <STRONG>^H</STRONG>) erases the character at the end of - the buffer, moving the cursor to the left. + If the screen's echo option is enabled (see <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG>), <STRONG>wget_wstr</STRONG> + updates <EM>win</EM> with <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>. Further, - If <EM>keypad</EM> mode is on for the window, <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are - both considered equivalent to the user's <EM>erase</EM> character. + <STRONG>o</STRONG> the wide erase character and its function key synonyms move the + cursor to the left, and - <STRONG>o</STRONG> The <EM>kill</EM> character (e.g., <STRONG>^U</STRONG>) erases the entire buffer, leaving the - cursor at the beginning of the buffer. + <STRONG>o</STRONG> the wide kill character returns the cursor to where it was located + when <STRONG>wget_wstr</STRONG> was called. - Characters input are echoed only if <STRONG>echo</STRONG> is currently on. In that - case, backspace is echoed as deletion of the previous character - (typically a left motion). + <STRONG>wgetn_wstr</STRONG> is similar, but reads at most <EM>n</EM> wide characters, aiding the + application to avoid overrunning the buffer to which <EM>wstr</EM> points. + <EM>curses</EM> ignores an attempt to input more than <EM>n</EM> wide characters (other + than the terminating line feed or carriage return), calling <STRONG><A HREF="curs_beep.3x.html">beep(3x)</A></STRONG>. + If <EM>n</EM> is negative, <STRONG>wgetn_wstr</STRONG> reads up to <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM> wide characters (see + <STRONG>sysconf(3)</STRONG>). - The <STRONG>getn_wstr</STRONG>, <STRONG>mvgetn_wstr</STRONG>, <STRONG>mvwgetn_wstr</STRONG>, and <STRONG>wgetn_wstr</STRONG> functions are - identical to the <STRONG>get_wstr</STRONG>, <STRONG>mvget_wstr</STRONG>, <STRONG>mvwget_wstr</STRONG>, and <STRONG>wget_wstr</STRONG> - functions, respectively, except that the <STRONG>*n_*</STRONG> versions read at most <EM>n</EM> - characters, letting the application prevent overflow of the input - buffer. + <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All of these functions return the integer <STRONG>OK</STRONG> upon successful - completion. If unsuccessful, they return <STRONG>ERR</STRONG>. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - X/Open defines no error conditions. + In <EM>ncurses</EM>, these functions fail if - In this implementation, these functions return an error + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> if the window pointer is null, + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, - <STRONG>o</STRONG> if its timeout expires without having any data, or + <STRONG>o</STRONG> <EM>wstr</EM> is a null pointer, or - <STRONG>o</STRONG> if the associated call to <STRONG>wget_wch</STRONG> failed. + <STRONG>o</STRONG> an internal <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG> call fails. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Any of these functions other than <STRONG>wgetn_wstr</STRONG> may be macros. + All of these functions except <STRONG>wgetn_wstr</STRONG> may be implemented as macros. + + Reading input that overruns the buffer pointed to by <EM>wstr</EM> causes + undefined results. Use the <STRONG>n</STRONG>-infixed functions, and allocate + sufficient storage for <EM>wstr</EM> -- at least <EM>n</EM>+1 times <STRONG>sizeof(wchar_t)</STRONG>. + + These functions cannot store a <STRONG>KEY_</STRONG> value in <EM>wstr</EM> because there is no + way to distinguish it from a valid <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> value. - Using <STRONG>get_wstr</STRONG>, <STRONG>mvget_wstr</STRONG>, <STRONG>mvwget_wstr</STRONG>, or <STRONG>wget_wstr</STRONG> to read a line - that overflows the array pointed to by <STRONG>wstr</STRONG> causes undefined results. - The use of <STRONG>getn_wstr</STRONG>, <STRONG>mvgetn_wstr</STRONG>, <STRONG>mvwgetn_wstr</STRONG>, or <STRONG>wgetn_wstr</STRONG>, - respectively, is recommended. + While these functions conceptually implement a series of calls to + <STRONG>wget_wch</STRONG>, they also temporarily change properties of the <EM>curses</EM> screen + to permit simple editing of the input buffer. Each function saves the + screen's state, calls <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG>, and, if the screen was in canonical + ("cooked") mode, <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG>. Before returning, it restores the saved + screen state. Other implementations differ in detail, affecting which + control characters they can accept in the buffer; see section + "PORTABILITY" below. - These functions cannot return <STRONG>KEY_</STRONG> values because there is no way to - distinguish a <STRONG>KEY_</STRONG> value from a valid <STRONG>wchar_t</STRONG> value. + Unlike <STRONG><A HREF="curs_getstr.3x.html">getstr(3x)</A></STRONG> and related functions of <EM>ncurses</EM>'s non-wide API, + these functions do not return <STRONG>KEY_RESIZE</STRONG> if a <EM>SIGWINCH</EM> event interrupts + the function. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>getn_wstr</STRONG>, <STRONG>wgetn_wstr</STRONG>, <STRONG>mvgetn_wstr</STRONG>, and <STRONG>mvwgetn_wstr</STRONG>'s handing of + negative <EM>n</EM> values is an <EM>ncurses</EM> extension. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in The Single Unix Specification, Version - 2. No error conditions are defined. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. - This implementation returns <STRONG>ERR</STRONG> if the window pointer is null, or if - the lower-level <STRONG>wget_wch</STRONG> call returns an <STRONG>ERR</STRONG>. In the latter case, an - <STRONG>ERR</STRONG> return without other data is treated as an end-of-file condition, - and the returned array contains a <STRONG>WEOF</STRONG> followed by a null <STRONG>wchar_t</STRONG>. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - X/Open curses documented these functions to pass an array of <STRONG>wchar_t</STRONG> in - 1997, but that was an error because of this part of the description: + Issue 4 documented these functions as passing an array of <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>, but + that was an error, conflicting with the following language in the + standard. - The effect of <STRONG>get_wstr</STRONG> is as though a series of calls to <STRONG>get_wch</STRONG> - were made, until a newline character, end-of-line character, or - end-of-file character is processed. + The effect of <EM>get</EM><STRONG>_</STRONG><EM>wstr</EM>() is as though a series of calls to + <EM>get</EM><STRONG>_</STRONG><EM>wch</EM>() were made, until a newline character, end-of-line + character, or end-of-file character is processed. - The latter function <EM>get</EM><STRONG>_</STRONG><EM>wch</EM> can return a negative value, while <STRONG>wchar_t</STRONG> - is a unsigned type. All of the vendors implement this using <STRONG>wint_t</STRONG>, - following the standard. + <EM>get</EM><STRONG>_</STRONG><EM>wch</EM> can return a negative value (<EM>WEOF</EM>), but <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> is a unsigned + type. All of the vendors implement these functions using <EM>wint</EM><STRONG>_</STRONG><EM>t</EM>, + following the Issue 7 standard. - X/Open Curses, Issue 7 (2009) is unclear regarding whether the - terminating <EM>null</EM> <STRONG>wchar_t</STRONG> value is counted in the length parameter <EM>n</EM>. - X/Open Curses, Issue 7 revised the corresponding description of - <STRONG>wgetnstr</STRONG> to address this issue. The unrevised description of - <STRONG>wget_nwstr</STRONG> can be interpreted either way. This implementation counts - the terminator in the length. + X/Open Curses Issue 7 is unclear whether the terminating null wide + character counts toward the length parameter <EM>n</EM>. A similar issue + affected <EM>wgetnstr</EM> in Issue 4, Version 2; Issue 7 revised that + function's description to address the issue, but not that of + <EM>wget</EM><STRONG>_</STRONG><EM>nwstr</EM>, leaving it ambiguous. <EM>ncurses</EM> counts the terminator in the + length. X/Open Curses does not specify what happens if the length <EM>n</EM> is negative. - <STRONG>o</STRONG> For analogy with <STRONG>wgetnstr</STRONG>, <EM>ncurses</EM> 6.2 uses a limit (based on - <STRONG>LINE_MAX</STRONG>). + <STRONG>o</STRONG> For consistency with <EM>wgetnstr</EM>, <EM>ncurses</EM> 6.2 uses a limit based on + <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM>. + + <STRONG>o</STRONG> Some other implementations (such as Solaris <EM>xcurses</EM>) do the same, + while others (<EM>PDCurses</EM>) do not permit a negative <EM>n</EM>. - <STRONG>o</STRONG> Some other implementations (such as Solaris xcurses) do the same, - while others (PDCurses) do not allow this. + <STRONG>o</STRONG> NetBSD 7 <EM>curses</EM> imitates <EM>ncurses</EM> 6.1 and earlier, treating a + negative <EM>n</EM> as an unbounded count of wide characters. - <STRONG>o</STRONG> NetBSD 7 curses imitates <EM>ncurses</EM> 6.1 in this regard, treating a <STRONG>-1</STRONG> - as an indefinite number of characters. + Implementations vary in their handling of input control characters. + + <STRONG>o</STRONG> While they may enable the screen's echo option, some do not take it + out of raw mode, and may take cbreak mode into account when + deciding whether to handle echoing within <EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM> or to rely on + it as a side effect of calling <EM>wget</EM><STRONG>_</STRONG><EM>wch</EM>. + + Since 1995, <EM>ncurses</EM> has provided handlers for <EM>SIGINTR</EM> and <EM>SIGQUIT</EM> + events, which are typically generated at the keyboard with <STRONG>^C</STRONG> and + <STRONG>^\</STRONG> respectively. In cbreak mode, those handlers catch a signal and + stop the program, whereas other implementations write those + characters into the buffer. + + <STRONG>o</STRONG> Starting with <EM>ncurses</EM> 6.3 (2021), <EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM> preserves raw mode if + the screen was already in that state, allowing one to enter the + characters the terminal interprets as interrupt and quit events + into the buffer, for consistency with SVr4 <EM>curses</EM>'s <EM>wgetnstr</EM>. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + X/Open Curses Issue 4 (1995) initially specified these functions. The + System V Interface Definition Version 4 of the same year specified + functions named <EM>wgetwstr</EM> and <EM>wgetnwstr</EM> (and the usual variants). These + were later additions to SVr4.<EM>x</EM>, not appearing in the first SVr4 (1989). + Except in name, their declarations did not differ from X/Open's later + <EM>wget</EM><STRONG>_</STRONG><EM>wstr</EM> and <EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM> until X/Open Curses Issue 7 (2009) eventually + changed the type of the buffer argument to a pointer to <EM>wint</EM><STRONG>_</STRONG><EM>t</EM>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> @@ -187,9 +232,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -198,7 +241,9 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="cu <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_getcchar.3x.html b/doc/html/man/curs_getcchar.3x.html index c1edf2841c36..26a5dff39b21 100644 --- a/doc/html/man/curs_getcchar.3x.html +++ b/doc/html/man/curs_getcchar.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 2001-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_getcchar.3x,v 1.49 2024/04/20 18:55:09 tom Exp @ + * @Id: curs_getcchar.3x,v 1.57 2025/02/23 13:48:31 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_getcchar 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_getcchar 3x 2025-02-23 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_getcchar 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_getcchar 3x 2025-02-23 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>getcchar</STRONG>, <STRONG>setcchar</STRONG> - convert between a wide-character string and a <EM>curses</EM> complex character @@ -54,149 +52,157 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>getcchar(</STRONG> - <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> - <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wc</EM><STRONG>,</STRONG> - <STRONG>attr_t</STRONG> <STRONG>*</STRONG><EM>attrs</EM><STRONG>,</STRONG> - <STRONG>short</STRONG> <STRONG>*</STRONG><EM>color</EM><STRONG>_</STRONG><EM>pair</EM><STRONG>,</STRONG> - <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM> <STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>setcchar(</STRONG> - <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wc</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> - <STRONG>short</STRONG> <EM>color</EM><STRONG>_</STRONG><EM>pair</EM><STRONG>,</STRONG> - <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM> <STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>getcchar(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wc</EM><STRONG>,</STRONG> + <STRONG>attr_t</STRONG> <STRONG>*</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG> <EM>opts</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>setcchar(cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wc</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG> <EM>opts</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> + The <EM>curses</EM> complex character data type <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> is a structure type + comprising a wide-character string, a set of attributes, and a color + pair identifier. The <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> structure is opaque; do not attempt to + access its members directly. The library provides functions to + manipulate this type. -</PRE><H3><a name="h3-getcchar">getcchar</a></H3><PRE> - The <STRONG>getcchar</STRONG> function gets a wide-character string and rendition from a - <STRONG>cchar_t</STRONG> argument. When <EM>wc</EM> is not a null pointer, the <STRONG>getcchar</STRONG> function - does the following: - - <STRONG>o</STRONG> Extracts information from a <STRONG>cchar_t</STRONG> value <EM>wch</EM> - <STRONG>o</STRONG> Stores the character attributes in the location pointed to by <EM>attrs</EM> +</PRE><H3><a name="h3-getcchar">getcchar</a></H3><PRE> + <STRONG>getcchar</STRONG> destructures a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> into its components. - <STRONG>o</STRONG> Stores the color pair in the location pointed to by <EM>color</EM><STRONG>_</STRONG><EM>pair</EM> + If <EM>wc</EM> is not a null pointer, <STRONG>getcchar</STRONG>: - <STRONG>o</STRONG> Stores the wide-character string, characters referenced by <EM>wch</EM>, - into the array pointed to by <EM>wc</EM>. + <STRONG>o</STRONG> stores the wide-character string in the <EM>curses</EM> complex character + <EM>wch</EM> into <EM>wc</EM>; - When <EM>wc</EM> is a null pointer, the <STRONG>getcchar</STRONG> function does the following: + <STRONG>o</STRONG> stores the attributes in <EM>attrs</EM>; and - <STRONG>o</STRONG> Obtains the number of wide characters pointed to by <EM>wch</EM> + <STRONG>o</STRONG> stores the color pair identifier in <EM>pair</EM>. - <STRONG>o</STRONG> Does not change the data referenced by <EM>attrs</EM> or <EM>color</EM><STRONG>_</STRONG><EM>pair</EM> + If <EM>wc</EM> is a null pointer, <STRONG>getcchar</STRONG> counts the <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> wide characters in + <EM>wch</EM>, returns that value, and leaves <EM>attrs</EM> and <EM>pair</EM> unchanged. </PRE><H3><a name="h3-setcchar">setcchar</a></H3><PRE> - The <STRONG>setcchar</STRONG> function initializes the location pointed to by <EM>wch</EM> by - using: + <STRONG>setcchar</STRONG> constructs a <EM>curses</EM> complex character <EM>wch</EM> from the components + <EM>wc</EM>, <EM>attrs</EM>, and <EM>pair</EM>. The wide-character string <EM>wch</EM> must be terminated + with a null wide character <STRONG>L'\0'</STRONG> and must contain at most one spacing + character, which, if present, must be the first wide character in the + string. - <STRONG>o</STRONG> The character attributes in <EM>attrs</EM> + Up to <STRONG>CCHARW_MAX</STRONG> - 1 non-spacing characters may follow (see + <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>). <EM>ncurses</EM> ignores any additional non-spacing + characters. - <STRONG>o</STRONG> The color pair in <EM>color</EM><STRONG>_</STRONG><EM>pair</EM> + The string may contain a single control character instead. In that + case, no non-spacing characters are allowed. - <STRONG>o</STRONG> The wide-character string pointed to by <EM>wc</EM>. The string must be - L'\0' terminated, contain at most one spacing character, which must - be the first. - Up to <STRONG>CCHARW_MAX</STRONG>-1 non-spacing characters may follow. Additional - non-spacing characters are ignored. +</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> + If <STRONG>getcchar</STRONG> is passed a null pointer as its <EM>wc</EM> argument, it returns the + number of wide characters for a given <EM>wch</EM> that it would store in <EM>wc</EM>, + counting a trailing null wide character. If <STRONG>getcchar</STRONG> is not passed a + null pointer as its <EM>wc</EM> argument, it returns <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on + failure. - The string may contain a single control character instead. In that - case, no non-spacing characters are allowed. + In <EM>ncurses</EM>, <STRONG>getcchar</STRONG> returns <STRONG>ERR</STRONG> if either <EM>attrs</EM> or <EM>pair</EM> is a null + pointer and <EM>wc</EM> is not. + <STRONG>setcchar</STRONG> returns <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. -</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - When <EM>wc</EM> is a null pointer, <STRONG>getcchar</STRONG> returns the number of wide - characters referenced by <EM>wch</EM>, including one for a trailing null. + In <EM>ncurses</EM>, <STRONG>setcchar</STRONG> returns <STRONG>ERR</STRONG> if - When <EM>wc</EM> is not a null pointer, <STRONG>getcchar</STRONG> returns <STRONG>OK</STRONG> upon successful - completion, and <STRONG>ERR</STRONG> otherwise. + <STRONG>o</STRONG> <EM>wch</EM> is a null pointer, - Upon successful completion, <STRONG>setcchar</STRONG> returns <STRONG>OK</STRONG>. Otherwise, it returns - <STRONG>ERR</STRONG>. + <STRONG>o</STRONG> <EM>wc</EM> starts with a (wide) control character and contains any other + wide characters, or + + <STRONG>o</STRONG> <EM>pair</EM> has a negative value. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - The <EM>wch</EM> argument may be a value generated by a call to <STRONG>setcchar</STRONG> or by a - function that has a <STRONG>cchar_t</STRONG> output argument. If <EM>wch</EM> is constructed by - any other means, the effect is unspecified. + <EM>wch</EM> may be a value stored by <STRONG>setcchar</STRONG> or another <EM>curses</EM> function with a + writable <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> argument. If <EM>wch</EM> is constructed by any other means, + the library's behavior is unspecified. </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - X/Open Curses documents the <EM>opts</EM> argument as reserved for future use, - saying that it must be null. This implementation uses that parameter - in ABI 6 for the functions which have a color pair parameter to support - extended color pairs: + X/Open Curses documents the <EM>opts</EM> argument as reserved for future use, + saying that it must be a null pointer. The <EM>ncurses</EM> 6 ABI uses it with + functions that have a color pair parameter to support extended color + pairs. - <STRONG>o</STRONG> For functions which modify the color, e.g., <STRONG>setcchar</STRONG>, if <EM>opts</EM> is - set it is treated as a pointer to <STRONG>int</STRONG>, and used to set the color - pair instead of the <STRONG>short</STRONG> pair parameter. + <STRONG>o</STRONG> In functions that assign colors, such as <STRONG>setcchar</STRONG>, if <EM>opts</EM> is not a + null pointer, <EM>ncurses</EM> treats it as a pointer to <EM>int</EM>, and interprets + it instead of the <EM>short</EM> <EM>pair</EM> parameter as a color pair identifier. - <STRONG>o</STRONG> For functions which retrieve the color, e.g., <STRONG>getcchar</STRONG>, if <EM>opts</EM> is - set it is treated as a pointer to <STRONG>int</STRONG>, and used to retrieve the - color pair as an <STRONG>int</STRONG> value, in addition retrieving it via the - standard pointer to <STRONG>short</STRONG> parameter. + <STRONG>o</STRONG> In functions that retrieve colors, such as <STRONG>getcchar</STRONG>, if <EM>opts</EM> is not + a null pointer, <EM>ncurses</EM> treats it as a pointer to <EM>int</EM>, and stores + the retrieved color pair identifier there as well as in the <EM>short</EM> + <EM>pair</EM> parameter (which may therefore undergo a narrowing + conversion). </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - The <STRONG>CCHARW_MAX</STRONG> symbol is specific to <EM>ncurses</EM>. X/Open Curses does not - provide details for the layout of the <STRONG>cchar_t</STRONG> structure. It tells what - data are stored in it: + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + + These functions are described in X/Open Curses Issue 4. It specifies + no error conditions for them. - <STRONG>o</STRONG> a spacing character (<STRONG>wchar_t</STRONG>, i.e., 32-bits). + X/Open Curses does not detail the layout of the <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> structure, + describing only its minimal required contents: - <STRONG>o</STRONG> non-spacing characters (again, <STRONG>wchar_t</STRONG>'s). + <STRONG>o</STRONG> a spacing wide character (<EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>), - <STRONG>o</STRONG> attributes (at least 16 bits, inferred from the various ACS- and - WACS-flags). + <STRONG>o</STRONG> at least five non-spacing wide characters (<EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>; see below), - <STRONG>o</STRONG> color pair (at least 16 bits, inferred from the <STRONG>unsigned</STRONG> <STRONG>short</STRONG> - type). + <STRONG>o</STRONG> attributes (at least 15 bits' worth, inferred from the count of + specified <EM>WA</EM><STRONG>_</STRONG> constants), - The non-spacing characters are optional, in the sense that zero or more - may be stored in a <STRONG>cchar_t</STRONG>. XOpen/Curses specifies a limit: + <STRONG>o</STRONG> a color pair identifier (at least 16 bits, inferred from the <EM>short</EM> + type used to encode it). + + Non-spacing characters are optional, in the sense that zero or more may + be stored in a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. XOpen/Curses specifies a limit: Implementations may limit the number of non-spacing characters that - can be associated with a spacing character, provided any limit is + can be associated with a spacing character, provided any limit is at least 5. - The Unix implementations at the time follow that limit: + Then-contemporary Unix implementations adhered to that limit. - <STRONG>o</STRONG> AIX 4 and OSF1 4 use the same declaration with an array of 5 non- - spacing characters <EM>z</EM> and a single spacing character <EM>c</EM>. + <STRONG>o</STRONG> AIX 4 and OSF/1 4 used the same declaration with a single spacing + wide character <EM>c</EM> and an array of 5 non-spacing wide characters <EM>z</EM>. - <STRONG>o</STRONG> HP-UX 10 uses an opaque structure with 28 bytes, which is large - enough for the 6 <STRONG>wchar_t</STRONG> values. + <STRONG>o</STRONG> HP-UX 10 used an opaque structure of 28 bytes, large enough for 6 + <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> values. - <STRONG>o</STRONG> Solaris <EM>xpg4</EM> curses uses a single array of 6 <STRONG>wchar_t</STRONG> values. + <STRONG>o</STRONG> Solaris <EM>xcurses</EM> uses a single array of 6 <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> values. - This implementation's <STRONG>cchar_t</STRONG> was defined in 1995 using <STRONG>5</STRONG> for the total - of spacing and non-spacing characters (<STRONG>CCHARW_MAX</STRONG>). That was probably - due to a misreading of the AIX 4 header files, because the X/Open - Curses document was not generally available at that time. Later (in - 2002), this detail was overlooked when beginning to implement the - functions using the structure. + <EM>ncurses</EM> defined its <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> in 1995 using 5 as the <EM>total</EM> of spacing and + non-spacing characters (<STRONG>CCHARW_MAX</STRONG>). That was probably due to a + misreading of the AIX 4 header files, because the X/Open Curses + document was not generally available at that time. Later (in 2002), + this detail was overlooked when work began to implement the functions + using the structure. - In practice, even four non-spacing characters may seem enough. X/Open - Curses documents possible uses for non-spacing characters, including - using them for ligatures between characters (a feature apparently not - supported by any curses implementation). Unicode does not limit the - (analogous) number of combining characters, so some applications may be - affected. + In practice, a mere four non-spacing characters may seem adequate. + X/Open Curses documents possible applications of non-spacing + characters, including their use as ligatures (a feature apparently not + supported by any <EM>curses</EM> implementation). Unicode does not limit the + (analogous) number of combining characters in a grapheme cluster; some + applications may be affected. <EM>ncurses</EM> can be compiled with a different + <STRONG>CCHARW_MAX</STRONG> value; doing so alters the library's ABI. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>, <STRONG>wcwidth(3)</STRONG> +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + X/Open Curses Issue 4 (1995) initially specified these functions. +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>, <STRONG>wcwidth(3)</STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG> +ncurses 6.6 2025-02-23 <STRONG><A HREF="curs_getcchar.3x.html">curs_getcchar(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -212,6 +218,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="cu <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_getch.3x.html b/doc/html/man/curs_getch.3x.html index fd8a8909f3e7..f095fdbb0675 100644 --- a/doc/html/man/curs_getch.3x.html +++ b/doc/html/man/curs_getch.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,37 +28,35 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_getch.3x,v 1.87 2024/04/20 19:18:18 tom Exp @ + * @Id: curs_getch.3x,v 1.134 2025/11/12 01:06:36 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_getch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_getch 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_getch 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_getch 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, <STRONG>ungetch</STRONG>, <STRONG>has_key</STRONG> - get (or push back) - characters from <EM>curses</EM> terminal keyboard + characters from <EM>curses</EM> terminal keyboard buffer </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> <STRONG>int</STRONG> <STRONG>getch(void);</STRONG> - <STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wgetch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>mvgetch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwgetch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwgetch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>ungetch(int</STRONG> <EM>c</EM><STRONG>);</STRONG> @@ -69,92 +67,114 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> </PRE><H3><a name="h3-Reading-Characters">Reading Characters</a></H3><PRE> - <STRONG>wgetch</STRONG> gathers a key stroke from the terminal keyboard associated with - a <EM>curses</EM> window <EM>win</EM>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this + <STRONG>wgetch</STRONG> gathers a key event from the terminal keyboard associated with a + <EM>curses</EM> window <EM>win</EM>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function. When input is pending, <STRONG>wgetch</STRONG> returns an integer identifying the key - stroke; for alphanumeric and punctuation keys, this value corresponds - to the character encoding used by the terminal. Use of the control key - as a modifier often results in a distinct code. The behavior of other - keys depends on whether <EM>win</EM> is in keypad mode; see subsection "Keypad - Mode" below. - - If no input is pending, then if the no-delay flag is set in the window - (see <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>), the function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits - until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> has been called, this - happens after one character is read. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> has been called, - it occurs when the next newline is read. If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been - called, <EM>curses</EM> waits until a character is typed or the specified delay - elapses. + event; for alphanumeric and punctuation keys, the space bar, and + (usually) the Backspace, Tab, Return, and Escape keys, this value + corresponds to the character encoding used by the terminal. Use of the + control key as a modifier, by holding it down while pressing and + releasing another key, often results in a distinct code. The behavior + of other keys depends on whether <EM>win</EM> is in keypad mode; see subsection + "Keypad Mode" below. + + If no input is pending, then if the no-delay flag is set in the window + (see <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG>), the function returns <STRONG>ERR</STRONG>; otherwise, <EM>curses</EM> waits + until the terminal has input. If <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> or <STRONG><A HREF="curs_inopts.3x.html">raw(3x)</A></STRONG> has been + called, this happens after <EM>curses</EM> reads one key event. If <STRONG><A HREF="curs_inopts.3x.html">nocbreak(3x)</A></STRONG> + or <STRONG><A HREF="curs_inopts.3x.html">noraw(3x)</A></STRONG> has been called, it occurs when <EM>curses</EM> reads a newline. + (Because the terminal's canonical or "cooked" mode is line-buffered, + multiple <STRONG>wgetch</STRONG> calls may then be necessary to empty the input queue.) + If <STRONG><A HREF="curs_inopts.3x.html">halfdelay(3x)</A></STRONG> has been called, <EM>curses</EM> waits until input is available + or the specified delay elapses. If <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> has been called, and the window is not a pad, <EM>curses</EM> writes the returned character <EM>c</EM> to the window (at the cursor position) per the following rules. - <STRONG>o</STRONG> If <EM>c</EM> matches the terminal's erase character, the cursor moves - leftward one position and the new position is erased as if + <STRONG>o</STRONG> If <EM>c</EM> matches the terminal's erase character (see <STRONG><A HREF="curs_termattrs.3x.html">erasechar(3x)</A></STRONG>), + and the cursor is not at the window's leftmost column, the cursor + moves leftward one position and the new position is erased as if <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> and then <STRONG><A HREF="curs_delch.3x.html">wdelch(3x)</A></STRONG> were called. When the window's keypad mode is enabled (see below), <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are handled the same way. <STRONG>o</STRONG> <EM>curses</EM> writes any other <EM>c</EM> to the window, as with <STRONG><A HREF="curs_addch.3x.html">wechochar(3x)</A></STRONG>. - <STRONG>o</STRONG> If the window has been moved or modified since the last call to - <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG>. + <STRONG>o</STRONG> If the window <EM>win</EM> has been moved or modified since the last call to + <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>, <EM>curses</EM> calls <STRONG>wrefresh</STRONG> on it. - If <EM>c</EM> is a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> returns + If <EM>c</EM> is a carriage return and <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> returns the character code for line feed instead. </PRE><H3><a name="h3-Keypad-Mode">Keypad Mode</a></H3><PRE> - To <EM>curses</EM>, key strokes not from the alphabetic section of the keyboard - (those corresponding to the ECMA-6 character set--see - <STRONG>ascii(7)</STRONG>--optionally modified by either the control or shift keys) are - treated as <EM>function</EM> keys. (In <EM>curses</EM>, the term "function key" includes - but is not limited to keycaps engraved with "F1", "PF1", and so on.) - If the window is in keypad mode, these produce a numeric code - corresponding to the <STRONG>KEY_</STRONG> symbols listed in subsection "Predefined Key - Codes" below; otherwise, they transmit a sequence of codes typically - starting with the escape character, and which must be collected with - multiple <STRONG>wgetch</STRONG> calls. - - <STRONG>o</STRONG> The <EM>curses.h</EM> header file declares many <EM>predefined</EM> <EM>function</EM> <EM>keys</EM> - whose names begin with <STRONG>KEY_</STRONG>; these object-like macros have values + Call <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> on a window to configure keypad mode when reading input + from it. In <EM>keypad</EM> <EM>mode</EM>, <EM>curses</EM> treats key strokes not from the + alphabetic section of the keyboard (those corresponding to the ECMA-6 + character set -- see <STRONG>ascii(7)</STRONG> -- optionally modified by either the + control or shift keys) as <EM>function</EM> keys. (In <EM>curses</EM>, the term + "function key" includes but is not limited to keycaps engraved with + "F1", "PF1", and so on.) If a window is in keypad mode, <STRONG>wgetch</STRONG> + translates these key strokes to a numeric code corresponding to the + <STRONG>KEY_</STRONG> symbols listed in subsection "Key Codes" below. If the window is + not in keypad mode, the input queue populates with the characters of + the function key's escape sequence, which the application must collect + individually with multiple <STRONG>wgetch</STRONG> calls. + + <STRONG>o</STRONG> The <EM>curses.h</EM> header file declares many <EM>function</EM> <EM>keys</EM> whose names + begin with <STRONG>KEY_</STRONG>; these object-like macros have integer values outside the range of eight-bit character codes. <STRONG>o</STRONG> In <EM>ncurses</EM>, <EM>user-defined</EM> <EM>function</EM> <EM>keys</EM> are configured with <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>; they have no names, but are also expected to have - values outside the range of eight-bit codes. + integer values outside the range of eight-bit character codes. A variable intended to hold a function key code must thus be of type <EM>short</EM> or larger. Most terminals one encounters follow the ECMA-48 standard insofar as their function keys produce character sequences prefixed with the - escape character ESC. This fact implies that <EM>curses</EM> cannot know - whether the terminal has sent an ESC key stroke or the beginning of a - function key's character sequence without waiting to see if, and how - soon, further input arrives. When <EM>curses</EM> reads such an ambiguous - character, it sets a timer. If the remainder of the sequence does not - arrive within the designated time, <STRONG>wgetch</STRONG> returns the prefix character; - otherwise, it returns the function key code corresponding to the unique - sequence defined by the terminal. Consequently, a user of a <EM>curses</EM> - application may experience a delay after pressing ESC while <EM>curses</EM> - disambiguates the input; see section "EXTENSIONS" below. If the window - is in "no time-out" mode, the timer does not expire; it is an infinite - (or very large) value. See <STRONG><A HREF="notimeout.3x.html">notimeout(3x)</A></STRONG>. Because function key - sequences usually begin with an escape character, the terminal may - appear to hang in no time-out mode after the user has pressed ESC. - Generally, further typing "awakens" <EM>curses</EM>. + escape character ESC. This fact implies that <EM>curses</EM> cannot distinguish + a user's press of the escape key (assuming it sends ESC) from the + beginning of a function key's character sequence without waiting to see + if, and how soon, further input arrives. + + <STRONG>o</STRONG> If the escape sequence matches a string capability defining a + function key for the terminal type (such as <STRONG>key_home</STRONG> (<STRONG>khome</STRONG>) or + <STRONG>key_up</STRONG> (<STRONG>kuu1</STRONG>)), <STRONG>wgetch</STRONG> returns the function key code corresponding + to the unique sequence defined by the terminal. + + <STRONG>o</STRONG> If the escape sequence matches no function keys defined for the + terminal type, call <STRONG>wgetch</STRONG> repeatedly to obtain the codes of the + individual characters of the sequence, in the order they occurred + in the input. + + <STRONG>o</STRONG> If <STRONG>wgetch</STRONG> cannot decide the validity of the input as a function key + because it has not read enough characters to disambiguate it, the + function waits until it has this information or the <EM>escape</EM> <EM>delay</EM> + elapses. Configure the escape delay with the global variable + <STRONG>ESCDELAY</STRONG>, an extension (see section "EXTENSIONS" below), or the + environment variable of the same name (see section "ENVIRONMENT" of + <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>), also an extension. + + Consequently, a user of a <EM>curses</EM> application that employs keypad mode + may experience a pause or "hang" after pressing the escape key while + <EM>curses</EM> collects sufficient characters to disambiguate the input. If + the window is in "no time-out" mode, the escape delay is effectively + infinite; see <STRONG><A HREF="notimeout.3x.html">notimeout(3x)</A></STRONG>. In the event of such a pause, further + typing "awakens" <EM>curses</EM>. </PRE><H3><a name="h3-Ungetting-Characters">Ungetting Characters</a></H3><PRE> <STRONG>ungetch</STRONG> places <EM>c</EM> into the input queue to be returned by the next call - to <STRONG>wgetch</STRONG>. A single input queue serves all windows. + to <STRONG>wgetch</STRONG>. A single input queue serves all windows associated with the + screen. -</PRE><H3><a name="h3-Predefined-Key-Codes">Predefined Key Codes</a></H3><PRE> +</PRE><H3><a name="h3-Key-Codes">Key Codes</a></H3><PRE> The header file <EM>curses.h</EM> defines the following function key codes. <STRONG>o</STRONG> Except for the special case of <STRONG>KEY_RESIZE</STRONG>, a window's keypad mode @@ -180,7 +200,6 @@ <STRONG>KEY_BACKSPACE</STRONG> Backspace <STRONG>KEY_F0</STRONG> Function keys; space for 64 keys is reserved <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> Function key <EM>n</EM> where 0 <= <EM>n</EM> <= 63 - <STRONG>KEY_DL</STRONG> Delete line <STRONG>KEY_IL</STRONG> Insert line <STRONG>KEY_DC</STRONG> Delete character @@ -246,7 +265,6 @@ <STRONG>KEY_SDL</STRONG> Shifted delete line key <STRONG>KEY_SEND</STRONG> Shifted end key <STRONG>KEY_SEOL</STRONG> Shifted clear line key - <STRONG>KEY_SEXIT</STRONG> Shifted exit key <STRONG>KEY_SFIND</STRONG> Shifted find key <STRONG>KEY_SHELP</STRONG> Shifted help key @@ -269,70 +287,82 @@ Many keyboards feature a nine-key directional pad. - +-----+------+-------+ - | A1 | up | A3 | - +-----+------+-------+ - |left | B2 | right | - +-----+------+-------+ - | C1 | down | C3 | - +-----+------+-------+ + +------+------+-------+ + | A1 | up | A3 | + +------+------+-------+ + | left | B2 | right | + +------+------+-------+ + | C1 | down | C3 | + +------+------+-------+ + Two of the symbols in the list above do <EM>not</EM> correspond to a physical key. <STRONG>o</STRONG> <STRONG>wgetch</STRONG> returns <STRONG>KEY_RESIZE</STRONG>, even if the window's keypad mode is - disabled, when <EM>ncurses</EM> handles a <STRONG>SIGWINCH</STRONG> signal; see <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> - and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>. + disabled, if <EM>ncurses</EM> has handled a <EM>SIGWINCH</EM> signal since <STRONG>wgetch</STRONG> was + called; see <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> and <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>. - <STRONG>o</STRONG> <STRONG>wgetch</STRONG> returns <STRONG>KEY_MOUSE</STRONG> to indicate that a mouse event is pending - collection; see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>. Receipt of this code requires a - window's keypad mode to be enabled, because to interpret mouse - input (as with with <STRONG>xterm(1)</STRONG>'s mouse prototocol), <EM>ncurses</EM> must read - an escape sequence, as with a function key. + <STRONG>o</STRONG> <STRONG>wgetch</STRONG> returns <STRONG>KEY_MOUSE</STRONG> to indicate that a mouse event is pending + collection; see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>. Receipt of this code requires a + window's keypad mode to be enabled, because to interpret mouse + input (as with <STRONG>xterm(1)</STRONG>'s mouse protocol), <EM>ncurses</EM> must read an + escape sequence, as with a function key. </PRE><H3><a name="h3-Testing-Key-Codes">Testing Key Codes</a></H3><PRE> - In <EM>ncurses</EM>, <STRONG>has_key</STRONG> returns a Boolean value indicating whether the - terminal type recognizes its parameter as a key code value. See also + In <EM>ncurses</EM>, <STRONG>has_key</STRONG> returns a Boolean value indicating whether the + terminal type recognizes its parameter as a key code value. See also <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> and <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Except for <STRONG>has_key</STRONG>, these functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on - failure. + <STRONG>wgetch</STRONG> returns a key code identifying the key event as described above, + which may include <STRONG>KEY_RESIZE</STRONG> or <STRONG>KEY_MOUSE</STRONG> indicating non-key events, or + <STRONG>ERR</STRONG> on failure. <STRONG>wgetch</STRONG> fails if its timeout expires without any data + arriving, which cannot happen if <STRONG><A HREF="nodelay.3x.html">nodelay(3x)</A></STRONG> is in effect on the + window. + + In <EM>ncurses</EM>, <STRONG>wgetch</STRONG> also fails if + + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - Functions taking a <EM>WINDOW</EM> pointer argument fail if the pointer is <STRONG>NULL</STRONG>. + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, or + + <STRONG>o</STRONG> execution was interrupted by a signal, in which case the library + sets <EM>errno</EM> to <EM>EINTR</EM>. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. - <STRONG>wgetch</STRONG> also fails if - - <STRONG>o</STRONG> its timeout expires without any data arriving, or + <STRONG>ungetch</STRONG> returns <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. In <EM>ncurses</EM>, <STRONG>ungetch</STRONG> + fails if - <STRONG>o</STRONG> execution was interrupted by a signal, in which case <STRONG>errno</STRONG> is set - to <STRONG>EINTR</STRONG>. + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, or - <STRONG>ungetch</STRONG> fails if there is no more room in the input queue. + <STRONG>o</STRONG> there is no more room in the input queue. <STRONG>has_key</STRONG> returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> + <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be implemented as macros. + <EM>curses</EM> discourages assignment of the ESC key to a discrete function by the programmer because the library requires a delay while it awaits the potential remainder of a terminal escape sequence. - Some key strokes are indistinguishable from control characters; for - example, <STRONG>KEY_ENTER</STRONG> may be the same as <STRONG>^M</STRONG>, and <STRONG>KEY_BACKSPACE</STRONG> may be the - same as <STRONG>^H</STRONG> or <STRONG>^?</STRONG>. Consult the terminal's <EM>terminfo</EM> entry to determine - whether this is the case; see <STRONG><A HREF="infocmp.1m.html">infocmp(1)</A></STRONG>. Some <EM>curses</EM> implementations, - including <EM>ncurses</EM>, honor the <EM>terminfo</EM> key definitions; others treat - such control characters specially. + Some key strokes are indistinguishable from control characters; for + example, <STRONG>KEY_ENTER</STRONG> may be the same as <STRONG>^M</STRONG>, and <STRONG>KEY_BACKSPACE</STRONG> may be the + same as <STRONG>^H</STRONG> or <STRONG>^?</STRONG>. Consult the <EM>terminfo</EM> entry for the terminal type to + determine whether this is the case; see <STRONG><A HREF="infocmp.1m.html">infocmp(1)</A></STRONG>. Some <EM>curses</EM> + implementations, including <EM>ncurses</EM>, honor the <EM>terminfo</EM> key definitions; + others treat such control characters specially. <EM>curses</EM> distinguishes the Enter keys in the alphabetic and numeric keypad sections of a keyboard because (most) terminals do. <STRONG>KEY_ENTER</STRONG> refers to the key on the numeric keypad and, like other function keys, - and is reliably recognized only if the window's keypad mode is enabled. + is reliably recognized only if the window's keypad mode is enabled. <STRONG>o</STRONG> The <EM>terminfo</EM> <STRONG>key_enter</STRONG> (<STRONG>kent</STRONG>) capability describes the character (sequence) sent by the Enter key of a terminal's numeric (or @@ -346,85 +376,92 @@ <STRONG>o</STRONG> It usually produces a control code for carriage return (<STRONG>^M</STRONG>) or line feed (<STRONG>^J</STRONG>). - <STRONG>o</STRONG> Depending on the terminal mode (raw, cbreak, or "cooked"), and - whether <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> or <STRONG><A HREF="curs_inopts.3x.html">nonl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> may return - either a carriage return or line feed upon an Enter or Return key + <STRONG>o</STRONG> Depending on the terminal mode (raw, cbreak, or canonical), and + whether <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> or <STRONG><A HREF="curs_inopts.3x.html">nonl(3x)</A></STRONG> has been called, <STRONG>wgetch</STRONG> may return + either a carriage return or line feed upon an Enter or Return key stroke. - Use of <STRONG>wgetch</STRONG> with <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> and neither <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> nor <STRONG><A HREF="curs_inopts.3x.html">raw(3x)</A></STRONG> is not + Use of <STRONG>wgetch</STRONG> with <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG> and neither <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG> nor <STRONG><A HREF="curs_inopts.3x.html">raw(3x)</A></STRONG> is not well-defined. - Historically, the list of key code macros above was influenced by the - function-key-rich keyboard of the AT&T 7300 (also known variously as - the "3B1", "Safari 4", and "UNIX PC"), a 1985 machine. Today's - computer keyboards are based that of the IBM PC/AT and tend to have + Historically, the list of key code macros above was influenced by the + keyboard of the AT&T 7300 (also known variously as the "3B1", "Safari + 4", and "UNIX PC"), a 1985 machine rich in function keys. Today's + computer keyboards are based on that of the IBM PC/AT and tend to have fewer. A <EM>curses</EM> application can expect such a keyboard to transmit key codes <STRONG>KEY_UP</STRONG>, <STRONG>KEY_DOWN</STRONG>, <STRONG>KEY_LEFT</STRONG>, <STRONG>KEY_RIGHT</STRONG>, <STRONG>KEY_HOME</STRONG>, <STRONG>KEY_END</STRONG>, <STRONG>KEY_PPAGE</STRONG> (Page Up), <STRONG>KEY_NPAGE</STRONG> (Page Down), <STRONG>KEY_IC</STRONG> (Insert), <STRONG>KEY_DC</STRONG> - (Delete), and <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> for 1 <= <EM>n</EM> <= 12. - - <STRONG>getch</STRONG>, <STRONG>mvgetch</STRONG>, and <STRONG>mvwgetch</STRONG> may be implemented as macros. + (Delete), <STRONG>KEY_A1</STRONG>, <STRONG>KEY_A3</STRONG>, <STRONG>KEY_B2</STRONG>, <STRONG>KEY_C1</STRONG>, <STRONG>KEY_C3</STRONG>, and <STRONG>KEY_F(</STRONG><EM>n</EM><STRONG>)</STRONG> for 1 <= + <EM>n</EM> <= 12. </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> In <EM>ncurses</EM>, when a window's "no time-out" mode is <EM>not</EM> set, the <STRONG>ESCDELAY</STRONG> - variable configures the duration of the timer used to disambiguate a - function key character sequence from a series of key strokes beginning + variable configures the duration of the timer used to disambiguate a + function key character sequence from a series of key strokes beginning with ESC typed by the user; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>. - <STRONG>has_key</STRONG> was designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and is not found in SVr4 <EM>curses</EM>, - 4.4BSD <EM>curses</EM>, or any other previous curses implementation. + <STRONG>has_key</STRONG> is an <EM>ncurses</EM> extension, and is not found in SVr4 <EM>curses</EM>, + 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> implementation. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> Applications employing <EM>ncurses</EM> extensions should condition their use on the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. - X/Open Curses, Issue 4 describes <STRONG>getch</STRONG>, <STRONG>wgetch</STRONG>, <STRONG>mvgetch</STRONG>, <STRONG>mvwgetch</STRONG>, and - <STRONG>ungetch</STRONG>. It specifies no error conditions for them. + Except as noted in section "EXTENSIONS" above, X/Open Curses Issue 4 + describes these functions. It specifies no error conditions for them. + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". - <STRONG>wgetch</STRONG> reads only single-byte characters. + <EM>wgetch</EM> reads only single-byte characters. - The echo behavior of these functions on input of <STRONG>KEY_</STRONG> or backspace - characters was not specified in the SVr4 documentation. This - description is adapted from X/Open Curses. + The echo behavior of these functions on input of <EM>KEY</EM><STRONG>_</STRONG> or backspace + characters is not documented in SVr4 <EM>curses</EM>. - The behavior of <STRONG>wgetch</STRONG> in the presence of signal handlers is - unspecified in the SVr4 documentation and X/Open Curses. In historical - <EM>curses</EM> implementations, it varied depending on whether the operating - system's dispatch of a signal to a handler interrupting a <STRONG>read(2)</STRONG> call - in progress, and also (in some implementations) whether an input - timeout or non-blocking mode has been set. Programmers concerned about - portability should be prepared for either of two cases: (a) signal - receipt does not interrupt <STRONG>wgetch</STRONG>; or (b) signal receipt interrupts - <STRONG>wgetch</STRONG> and causes it to return <STRONG>ERR</STRONG> with <STRONG>errno</STRONG> set to <STRONG>EINTR</STRONG>. + The behavior of <EM>wgetch</EM> in the presence of signal handlers is not + documented in SVr4 <EM>curses</EM> and is unspecified by X/Open Curses. In + historical <EM>curses</EM> implementations, it varied depending on whether the + operating system's dispatch of a signal to a handler interrupted a + <STRONG>read(2)</STRONG> call in progress, and also (in some implementations) whether an + input timeout or non-blocking mode had been set. A portable <EM>curses</EM> + application prepares for two cases: (a) signal receipt does not + interrupt <EM>wgetch</EM>; and (b) signal receipt interrupts <EM>wgetch</EM> and causes + it to return <EM>ERR</EM> with <EM>errno</EM> set to <EM>EINTR</EM>. - <STRONG>KEY_MOUSE</STRONG> is mentioned in X/Open Curses, along with a few related <EM>term-</EM> + <EM>KEY</EM><STRONG>_</STRONG><EM>MOUSE</EM> is mentioned in X/Open Curses, along with a few related <EM>term-</EM> <EM>info</EM> capabilities, but no higher-level functions use the feature. The implementation in <EM>ncurses</EM> is an extension. - <STRONG>KEY_RESIZE</STRONG> and <STRONG>has_key</STRONG> are extensions first implemented for <EM>ncurses</EM>. + <EM>KEY</EM><STRONG>_</STRONG><EM>RESIZE</EM> and <EM>has</EM><STRONG>_</STRONG><EM>key</EM> are extensions first implemented for <EM>ncurses</EM>. By 2022, <EM>PDCurses</EM> and NetBSD <EM>curses</EM> had added them along with - <STRONG>KEY_MOUSE</STRONG>. + <EM>KEY</EM><STRONG>_</STRONG><EM>MOUSE</EM>. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library - in its wide-character configuration (<EM>ncursesw</EM>). +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced <EM>wgetch</EM> and its variants. - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>, - <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, - <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>, <STRONG>ascii(7)</STRONG> + SVr3 (1987) added <EM>ungetch</EM>. + + <EM>ncurses</EM> 1.9.9g (1996) furnished the <EM>has</EM><STRONG>_</STRONG><EM>key</EM> extension. - ECMA-6 "7-bit coded Character Set" <https://ecma-international.org/ + +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + ECMA-6 "7-bit coded Character Set" <https://ecma-international.org/ publications-and-standards/standards/ecma-6/> - ECMA-48 "Control Functions for Coded Character Sets" <https:// + ECMA-48 "Control Functions for Coded Character Sets" <https:// ecma-international.org/publications-and-standards/standards/ecma-48/> + <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library + in its wide-character configuration (<EM>ncursesw</EM>). + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>, + <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, + <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG>, <STRONG>ascii(7)</STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -435,7 +472,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF= <li><a href="#h3-Reading-Characters">Reading Characters</a></li> <li><a href="#h3-Keypad-Mode">Keypad Mode</a></li> <li><a href="#h3-Ungetting-Characters">Ungetting Characters</a></li> -<li><a href="#h3-Predefined-Key-Codes">Predefined Key Codes</a></li> +<li><a href="#h3-Key-Codes">Key Codes</a></li> <li><a href="#h3-Testing-Key-Codes">Testing Key Codes</a></li> </ul> </li> @@ -443,6 +480,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF= <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_getstr.3x.html b/doc/html/man/curs_getstr.3x.html index 0142df971c21..97565fcac72a 100644 --- a/doc/html/man/curs_getstr.3x.html +++ b/doc/html/man/curs_getstr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,222 +27,250 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_getstr.3x,v 1.58 2024/04/20 19:18:18 tom Exp @ + * @Id: curs_getstr.3x,v 1.94 2025/10/21 00:09:04 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_getstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_getstr 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_getstr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_getstr 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>getstr</STRONG>, <STRONG>getnstr</STRONG>, <STRONG>wgetstr</STRONG>, <STRONG>wgetnstr</STRONG>, <STRONG>mvgetstr</STRONG>, <STRONG>mvgetnstr</STRONG>, <STRONG>mvwgetstr</STRONG>, - <STRONG>mvwgetnstr</STRONG> - accept character strings from <EM>curses</EM> terminal keyboard + <STRONG>mvwgetnstr</STRONG> - read a character string from <EM>curses</EM> terminal keyboard </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>getstr(char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>getnstr(char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wgetstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wgetnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>getstr(char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wgetstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvgetstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwgetstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvgetstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwgetstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvgetnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwgetnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>getnstr(char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wgetnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvgetnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwgetnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The function <STRONG>wgetnstr</STRONG> is equivalent to a series of calls to <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>, - until a newline or carriage return terminates the series: + <STRONG>wgetstr</STRONG> populates a user-supplied string buffer <EM>str</EM> by repeatedly + calling <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> with the <EM>win</EM> argument until a line feed or carriage + return character is input. The function - <STRONG>o</STRONG> The terminating character is not included in the returned string. + <STRONG>o</STRONG> does not copy the terminating character to <EM>str</EM>; - <STRONG>o</STRONG> In all instances, the end of the string is terminated by a NUL. + <STRONG>o</STRONG> always terminates <EM>str</EM> with a null character; - <STRONG>o</STRONG> The function stores the result in the area pointed to by the <EM>str</EM> - parameter. + <STRONG>o</STRONG> interprets the screen's erase and kill characters (see + <STRONG><A HREF="curs_termattrs.3x.html">erasechar(3x)</A></STRONG> and <STRONG><A HREF="curs_termattrs.3x.html">killchar(3x)</A></STRONG>); - <STRONG>o</STRONG> The function reads at most <EM>n</EM> characters, thus preventing a possible - overflow of the input buffer. + <STRONG>o</STRONG> recognizes function keys only if the screen's keypad option is + enabled (see <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG>); - Any attempt to enter more characters (other than the terminating - newline or carriage return) causes a beep. + <STRONG>o</STRONG> treats the function keys <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> the same as the + erase character; and - Function keys also cause a beep and are ignored. + <STRONG>o</STRONG> discards function key inputs other than those treated as the erase + or kill characters, calling <STRONG><A HREF="curs_beep.3x.html">beep(3x)</A></STRONG>. - The user's <EM>erase</EM> and <EM>kill</EM> characters are interpreted: + If any characters have been written to the input buffer, the erase + character replaces the character at the current position in the buffer + with a null character, then decrements the position by one; the kill + character does the same repeatedly, backtracking to the beginning of + the buffer. - <STRONG>o</STRONG> The <EM>erase</EM> character (e.g., <STRONG>^H</STRONG>) erases the character at the end of - the buffer, moving the cursor to the left. + If the screen's echo option is enabled (see <STRONG><A HREF="curs_inopts.3x.html">echo(3x)</A></STRONG>), <STRONG>wgetstr</STRONG> updates + <EM>win</EM> with <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG>. Further, - If <EM>keypad</EM> mode is on for the window, <STRONG>KEY_LEFT</STRONG> and <STRONG>KEY_BACKSPACE</STRONG> are - both considered equivalent to the user's <EM>erase</EM> character. + <STRONG>o</STRONG> the erase character and its function key synonyms move the cursor + to the left (if not already where it was located when <STRONG>wgetstr</STRONG> was + called) and - <STRONG>o</STRONG> The <EM>kill</EM> character (e.g., <STRONG>^U</STRONG>) erases the entire buffer, leaving the - cursor at the beginning of the buffer. + <STRONG>o</STRONG> the kill character returns the cursor to where it was located when + <STRONG>wgetstr</STRONG> was called. - Characters input are echoed only if <STRONG>echo</STRONG> is currently on. In that - case, backspace is echoed as deletion of the previous character - (typically a left motion). + <STRONG>wgetnstr</STRONG> is similar, but reads at most <EM>n</EM> characters, aiding the + application to avoid overrunning the buffer to which <EM>str</EM> points. + <EM>curses</EM> ignores an attempt to input more than <EM>n</EM> characters (other than + the terminating line feed or carriage return), calling <STRONG><A HREF="curs_beep.3x.html">beep(3x)</A></STRONG>. If <EM>n</EM> + is negative, <STRONG>wgetn_wstr</STRONG> reads up to <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM> characters (see + <STRONG>sysconf(3)</STRONG>). - The <STRONG>getnstr</STRONG>, <STRONG>mvgetnstr</STRONG>, <STRONG>mvwgetnstr</STRONG>, and <STRONG>wgetnstr</STRONG> functions are - identical to the <STRONG>getstr</STRONG>, <STRONG>mvgetstr</STRONG>, <STRONG>mvwgetstr</STRONG>, and <STRONG>wgetstr</STRONG> functions, - respectively, except that the <STRONG>*n*</STRONG> versions read at most <EM>n</EM> characters, - letting the application prevent overflow of the input buffer. + <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All of these functions return the integer <STRONG>OK</STRONG> upon successful - completion. (SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>") If - unsuccessful, they return <STRONG>ERR</STRONG>. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - X/Open defines no error conditions. + In <EM>ncurses</EM>, these functions fail if - In this implementation, these functions return an error + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> if the window pointer is null, + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, - <STRONG>o</STRONG> if its timeout expires without having any data, or + <STRONG>o</STRONG> <EM>str</EM> is a null pointer, or - <STRONG>o</STRONG> if the associated call to <STRONG>wgetch</STRONG> failed. + <STRONG>o</STRONG> an internal <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> call fails. - This implementation provides an extension as well. If a <STRONG>SIGWINCH</STRONG> - interrupts the function, it will return <STRONG>KEY_RESIZE</STRONG> rather than <STRONG>OK</STRONG> or - <STRONG>ERR</STRONG>. + Further, in <EM>ncurses</EM>, these functions return <STRONG>KEY_RESIZE</STRONG> if a <EM>SIGWINCH</EM> + event interrupts the function. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Any of these functions other than <STRONG>wgetnstr</STRONG> may be macros. + All of these functions except <STRONG>wgetnstr</STRONG> may be implemented as macros. - Using <STRONG>getstr</STRONG>, <STRONG>mvgetstr</STRONG>, <STRONG>mvwgetstr</STRONG>, or <STRONG>wgetstr</STRONG> to read a line that - overflows the array pointed to by <STRONG>str</STRONG> causes undefined results. The - use of <STRONG>getnstr</STRONG>, <STRONG>mvgetnstr</STRONG>, <STRONG>mvwgetnstr</STRONG>, or <STRONG>wgetnstr</STRONG>, respectively, is - recommended. + Reading input that overruns the buffer pointed to by <EM>str</EM> causes + undefined results. Use the <STRONG>n</STRONG>-infixed functions, and allocate + sufficient storage for <EM>str</EM> -- at least <EM>n</EM>+1 times <STRONG>sizeof(char)</STRONG>. + While these functions conceptually implement a series of calls to + <STRONG>wgetch</STRONG>, they also temporarily change properties of the <EM>curses</EM> screen to + permit simple editing of the input buffer. Each function saves the + screen's state, calls <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG>, and, if the screen was in canonical + ("cooked") mode, <STRONG><A HREF="curs_inopts.3x.html">cbreak(3x)</A></STRONG>. Before returning, it restores the saved + screen state. Other implementations differ in detail, affecting which + control characters they can accept in the buffer; see section + "PORTABILITY" below. -</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in The Single Unix Specification, Version - 2. No error conditions are defined. - This implementation returns <STRONG>ERR</STRONG> if the window pointer is null, or if - the lower-level <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> call returns an <STRONG>ERR</STRONG>. +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>getnstr</STRONG>, <STRONG>wgetnstr</STRONG>, <STRONG>mvgetnstr</STRONG>, and <STRONG>mvwgetnstr</STRONG>'s handing of negative <EM>n</EM> + values is an <EM>ncurses</EM> extension. - SVr3 and early SVr4 curses implementations did not reject function - keys; the SVr4.0 documentation claimed that "special keys" (such as - function keys, "home" key, "clear" key, <EM>etc</EM>.) are "interpreted", - without giving details. It lied. In fact, the "character" value - appended to the string by those implementations was predictable but not - useful (being, in fact, the low-order eight bits of the key's KEY_ - value). + The return value <STRONG>KEY_RESIZE</STRONG> is an <EM>ncurses</EM> extension. - The functions <STRONG>getnstr</STRONG>, <STRONG>mvgetnstr</STRONG>, and <STRONG>mvwgetnstr</STRONG> were present but not - documented in SVr4. - X/Open Curses, Issue 5 (2007) stated that these functions "read at most - <EM>n</EM> bytes" but did not state whether the terminating NUL is counted in - that limit. X/Open Curses, Issue 7 (2009) changed that to say they - "read at most <EM>n</EM>-1 bytes" to allow for the terminating NUL. As of 2018, - some implementations count it, some do not: +</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them, but indicates that <EM>wgetnstr</EM> and its variants read + "the entire multi-byte sequence associated with a character" and "fail" + if <EM>n</EM> and <EM>str</EM> together do not describe a buffer "large enough to contain + any complete characters". In <EM>ncurses</EM>, however, <EM>wgetch</EM> reads only + single-byte characters, so this scenario does not arise. + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". - <STRONG>o</STRONG> <EM>ncurses</EM> 6.1 and PDCurses do not count the NUL in the given limit, - while + SVr3 and early SVr4 <EM>curses</EM> implementations did not reject function + keys; the SVr4 documentation asserted that, like the screen's erase and + kill characters, they were - <STRONG>o</STRONG> Solaris SVr4 and NetBSD curses count the NUL as part of the limit. + interpreted, as well as any special keys (such as function keys, + "home" key, "clear" key, <EM>etc.</EM>) - <STRONG>o</STRONG> Solaris xcurses provides both: its wide-character <STRONG>wget_nstr</STRONG> - reserves a NUL, but its <STRONG>wgetnstr</STRONG> does not count the NUL - consistently. + without further detail. It lied. The "character" value appended to + the string by those implementations was predictable but not useful -- + being, in fact, the low-order eight bits of the key code's <EM>KEY</EM><STRONG>_</STRONG> + constant value. (The same language, unchanged except for styling, + survived into X/Open Curses Issue 4, Version 2 but disappeared from + Issue 7.) - In SVr4 curses, a negative value of <EM>n</EM> tells <STRONG>wgetnstr</STRONG> to assume that the - caller's buffer is large enough to hold the result, i.e., to act like - <STRONG>wgetstr</STRONG>. X/Open Curses does not mention this (or anything related to - negative or zero values of <EM>n</EM>), however most implementations use the - feature, with different limits: + A draft of X/Open Curses Issue 5 (which never saw final release) stated + that these functions "read at most <EM>n</EM> bytes" but did not state whether + the terminating null character counted toward that limit. X/Open + Curses Issue 7 changed that to say they "read at most <EM>n</EM>-1 bytes" to + allow for the terminating null character. As of 2018, some + implementations count it, some do not. - <STRONG>o</STRONG> Solaris SVr4 curses and PDCurses limit the result to 255 bytes. - Other Unix systems than Solaris are likely to use the same limit. + <STRONG>o</STRONG> <EM>ncurses</EM> 6.1 and <EM>PDCurses</EM> do not count the null character toward the + limit, while Solaris and NetBSD <EM>curses</EM> do. - <STRONG>o</STRONG> Solaris xcurses limits the result to <STRONG>LINE_MAX</STRONG> bytes. + <STRONG>o</STRONG> Solaris <EM>xcurses</EM> offers both behaviors: its wide-character + <EM>wgetn</EM><STRONG>_</STRONG><EM>wstr</EM> reserves room for a wide null character, but its non- + wide <EM>wgetnstr</EM> does not consistently count a null character toward + the limit. - <STRONG>o</STRONG> NetBSD 7 assumes no particular limit for the result from <STRONG>wgetstr</STRONG>. - However, it limits the <STRONG>wgetnstr</STRONG> parameter <EM>n</EM> to ensure that it is - greater than zero. + X/Open Curses does not specify what happens if the length <EM>n</EM> is + negative. - A comment in NetBSD's source code states that this is specified in - SUSv2. + <STRONG>o</STRONG> <EM>ncurses</EM> 6.2 uses <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM> or a larger (system-dependent) value + provided by <STRONG>sysconf(3)</STRONG>. If neither <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM> nor <EM>sysconf</EM> is + available, <EM>ncurses</EM> uses the POSIX minimum value for <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM> + (2048). In either case, it reserves a byte for the terminating + null character. - <STRONG>o</STRONG> <EM>ncurses</EM> (before 6.2) assumes no particular limit for the result - from <STRONG>wgetstr</STRONG>, and treats the <EM>n</EM> parameter of <STRONG>wgetnstr</STRONG> like SVr4 - curses. + <STRONG>o</STRONG> In SVr4 <EM>curses</EM>, a negative <EM>n</EM> tells <EM>wgetnstr</EM> to assume that the + caller's buffer is large enough to hold the result; that is, the + function then acts like <EM>wgetstr</EM>. X/Open Curses does not mention + this behavior (or anything related to nonpositive <EM>n</EM> values), + however most <EM>curses</EM> libraries implement it. Most implementations + nevertheless enforce an upper limit on the count of bytes they + write to the destination buffer <EM>str</EM>. - <STRONG>o</STRONG> <EM>ncurses</EM> 6.2 uses <STRONG>LINE_MAX</STRONG>, or a larger (system-dependent) value - which the <STRONG>sysconf</STRONG> function may provide. If neither <STRONG>LINE_MAX</STRONG> or - <STRONG>sysconf</STRONG> is available, <EM>ncurses</EM> uses the POSIX value for <STRONG>LINE_MAX</STRONG> (a - 2048 byte limit). In either case, it reserves a byte for the - terminating NUL. + <STRONG>o</STRONG> BSD <EM>curses</EM> lacked <EM>wgetnstr</EM>, and its <EM>wgetstr</EM> wrote to <EM>str</EM> + unboundedly, as did that in SVr2. - Although <STRONG>getnstr</STRONG> is equivalent to a series of calls to <STRONG>getch</STRONG>, it also - makes changes to the curses modes to allow simple editing of the input - buffer: + <STRONG>o</STRONG> <EM>PDCurses</EM>, and SVr3 and later, and Solaris <EM>curses</EM> limit both + functions to writing 256 bytes. Other System V-based platforms + likely use the same limit. - <STRONG>o</STRONG> <STRONG>getnstr</STRONG> saves the current value of the <STRONG>nl</STRONG>, <STRONG>echo</STRONG>, <STRONG>raw</STRONG> and <STRONG>cbreak</STRONG> - modes, and sets <STRONG>nl</STRONG>, <STRONG>noecho</STRONG>, <STRONG>noraw</STRONG>, and <STRONG>cbreak</STRONG>. + <STRONG>o</STRONG> Solaris <EM>xcurses</EM> limits the write to <EM>LINE</EM><STRONG>_</STRONG><EM>MAX</EM> bytes (see + <STRONG>sysconf(3)</STRONG>). - <STRONG>getnstr</STRONG> handles the echoing of characters, rather than relying on - the caller to set an appropriate mode. + <STRONG>o</STRONG> NetBSD 7 <EM>curses</EM> imposes no particular limit on the length of the + write, but does validate <EM>n</EM> to ensure that it is greater than zero. + A comment in NetBSD's source code asserts that SUSv2 specifies + this. - <STRONG>o</STRONG> It also obtains the <EM>erase</EM> and <EM>kill</EM> characters from <STRONG>erasechar</STRONG> and - <STRONG>killchar</STRONG>, respectively. + Implementations vary in their handling of input control characters. - <STRONG>o</STRONG> On return, <STRONG>getnstr</STRONG> restores the modes to their previous values. + <STRONG>o</STRONG> While they may enable the screen's echo option, some do not take it + out of raw mode, and may take cbreak mode into account when + deciding whether to handle echoing within <EM>wgetnstr</EM> or to rely on it + as a side effect of calling <EM>wgetch</EM>. - Other implementations differ in their treatment of special characters: + <STRONG>o</STRONG> Originally, <EM>ncurses</EM>, like its progenitor <EM>pcurses</EM>, had its <EM>wgetnstr</EM> + call <EM>noraw</EM> and <EM>cbreak</EM> before accepting input. That may have been + done to make function keys work; it is not necessary with modern + <EM>ncurses</EM>. - <STRONG>o</STRONG> While they may set the <EM>echo</EM> mode, other implementations do not - modify the <EM>raw</EM> mode, They may take the <EM>cbreak</EM> mode set by the - caller into account when deciding whether to handle echoing within - <STRONG>getnstr</STRONG> or as a side-effect of the <STRONG>getch</STRONG> calls. + Since 1995, <EM>ncurses</EM> has provided handlers for <EM>SIGINTR</EM> and <EM>SIGQUIT</EM> + events, which are typically generated at the keyboard with <STRONG>^C</STRONG> and + <STRONG>^\</STRONG> respectively. In cbreak mode, those handlers catch a signal and + stop the program, whereas other implementations write those + characters into the buffer. - <STRONG>o</STRONG> The original <EM>ncurses</EM> (as <EM>pcurses</EM> in 1986) set <STRONG>noraw</STRONG> and <STRONG>cbreak</STRONG> when - accepting input for <STRONG>getnstr</STRONG>. That may have been done to make - function- and cursor-keys work; it is not necessary with <EM>ncurses</EM>. + <STRONG>o</STRONG> Starting with <EM>ncurses</EM> 6.3 (2021), <EM>wgetnstr</EM> preserves raw mode if + the screen was already in that state, allowing one to enter the + characters the terminal interprets as interrupt and quit events + into the buffer, for better compatibility with SVr4 <EM>curses</EM>. - Since 1995, <EM>ncurses</EM> has provided signal handlers for INTR and QUIT - (e.g., <STRONG>^C</STRONG> or <STRONG>^\</STRONG>). With the <STRONG>noraw</STRONG> and <STRONG>cbreak</STRONG> settings, those may - catch a signal and stop the program, where other implementations - allow one to enter those characters in the buffer. - <STRONG>o</STRONG> Starting in 2021 (<EM>ncurses</EM> 6.3), <STRONG>getnstr</STRONG> sets <STRONG>raw</STRONG>, rather than <STRONG>noraw</STRONG> - and <STRONG>cbreak</STRONG> for better compatibility with SVr4-curses, e.g., - allowing one to enter a <STRONG>^C</STRONG> into the buffer. +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced <EM>wgetstr</EM> along with its variants. + + SVr3.1 (1987) added <EM>wgetnstr</EM>, but none of its variants. + + X/Open Curses Issue 4 (1995) specified <EM>getnstr</EM>, <EM>mvgetnstr</EM>, and + <EM>mvwgetnstr</EM>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in its wide-character configuration (<EM>ncursesw</EM>). - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>, <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, + <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG>, -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -251,7 +279,9 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF=" <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_getyx.3x.html b/doc/html/man/curs_getyx.3x.html index 1857170022bd..41a26bd070fd 100644 --- a/doc/html/man/curs_getyx.3x.html +++ b/doc/html/man/curs_getyx.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2020-2023,2024 Thomas E. Dickey * + * Copyright 2020-2024,2025 Thomas E. Dickey * * Copyright 1998-2007,2010 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_getyx.3x,v 1.44 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_getyx.3x,v 1.55 2025/02/01 22:48:11 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_getyx 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_getyx 3x 2025-02-01 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_getyx 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_getyx 3x 2025-02-01 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>getyx</STRONG>, <STRONG>getparyx</STRONG>, <STRONG>getbegyx</STRONG>, <STRONG>getmaxyx</STRONG> - get <EM>curses</EM> cursor and window coordinates @@ -55,61 +53,66 @@ <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> <STRONG>void</STRONG> <STRONG>getyx(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>getparyx(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> <STRONG>void</STRONG> <STRONG>getbegyx(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> <STRONG>void</STRONG> <STRONG>getmaxyx(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>getparyx(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> -</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The <STRONG>getyx</STRONG> macro places the current cursor position of the given window - in the two integer variables <EM>y</EM> and <EM>x</EM>. - If <EM>win</EM> is a subwindow, the <STRONG>getparyx</STRONG> macro places the beginning - coordinates of the subwindow relative to the parent window into two - integer variables <EM>y</EM> and <EM>x</EM>. Otherwise, <STRONG>-1</STRONG> is placed into <EM>y</EM> and <EM>x</EM>. +</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> + These macros obtain the cursor position and bounds information of a + <EM>curses</EM> window <EM>win</EM>. <STRONG>getyx</STRONG> stores <EM>win</EM>'s cursor position in the variables + <EM>y</EM> and <EM>x</EM>. <STRONG>getmaxyx</STRONG> stores <EM>win</EM>'s maximum valid line and column numbers + in <EM>y</EM> and <EM>x</EM>, respectively. <STRONG>getbegyx</STRONG> similarly stores the position of + <EM>win</EM>'s origin relative to that of the screen (for <STRONG>stdscr</STRONG>, these + coordinates are always <STRONG>0</STRONG>). - Like <STRONG>getyx</STRONG>, the <STRONG>getbegyx</STRONG> and <STRONG>getmaxyx</STRONG> macros store the current - beginning coordinates and size of the specified window. + If <EM>win</EM> is a subwindow (see <STRONG><A HREF="subwin.3x.html">subwin(3x)</A></STRONG>), the <STRONG>getparyx</STRONG> macro places the + coordinates of its origin relative to its parent window into <EM>y</EM> and <EM>x</EM>, + and <STRONG>-1</STRONG> into both if it is not. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The return values of these macros are undefined (i.e., they should not - be used as the right-hand side of assignment statements). + No return values are defined for macros. Do not use them as the right- + hand side of assignment statements. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All of these interfaces are macros. A "&" is not necessary before the - variables <EM>y</EM> and <EM>x</EM>. + All of these interfaces are implemented as macros. An "&" operator is + not necessary before the variables <EM>y</EM> and <EM>x</EM>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - The <STRONG>getyx</STRONG>, <STRONG>getparyx</STRONG>, <STRONG>getbegyx</STRONG> and <STRONG>getmaxyx</STRONG> macros are described in - X/Open Curses, Issue 4. + These macros are described in X/Open Curses Issue 4. - This implementation also provides functions <STRONG>getbegx</STRONG>, <STRONG>getbegy</STRONG>, <STRONG>getcurx</STRONG>, - <STRONG>getcury</STRONG>, <STRONG>getmaxx</STRONG>, <STRONG>getmaxy</STRONG>, <STRONG>getparx</STRONG> and <STRONG>getpary</STRONG> for compatibility with - older versions of <EM>curses</EM>; see <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>. + <EM>ncurses</EM> also provides functions <EM>getbegy</EM>, <EM>getbegx</EM>, <EM>getcury</EM>, <EM>getcurx</EM>, + <EM>getmaxy</EM>, <EM>getmaxx</EM>, <EM>getpary</EM>, and <EM>getparx</EM> for compatibility with System V + <EM>curses</EM> that were not standardized; see <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>. - Although X/Open Curses does not address this, many implementations - provide members of the <STRONG>WINDOW</STRONG> structure containing values corresponding - to these macros. For best portability, do not rely on using the data - in <STRONG>WINDOW</STRONG>, since some implementations make <STRONG>WINDOW</STRONG> opaque (do not allow - direct use of its members). + Although X/Open Curses does not address the issue, many implementations + expose members of the <EM>WINDOW</EM> structure containing values corresponding + to these macros. Do not rely on their availability; some + implementations make <EM>WINDOW</EM> opaque (that is, they do not allow direct + access to its members). Besides the problem of opaque structures, the data stored in like-named - members may not have like-values in different implementations. For - example, the <STRONG>WINDOW._maxx</STRONG> and <STRONG>WINDOW._maxy</STRONG> values in <EM>ncurses</EM> have (at - least since release 1.8.1) differed by one from some other - implementations. The difference is hidden by means of the macro - <STRONG>getmaxyx</STRONG>. + members may not have values of the same meaning across different + implementations. For example, the values of <EM>WINDOW.</EM><STRONG>_</STRONG><EM>maxx</EM> and + <EM>WINDOW.</EM><STRONG>_</STRONG><EM>maxy</EM> in <EM>ncurses</EM> have long differed by one from some other + implementations. The <EM>getmaxyx</EM> macro hides this difference. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>, <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced <EM>getyx</EM>. + + SVr3 (1987) added <EM>getbegyx</EM> and <EM>getmaxyx</EM>. SVr3.1 later that year + supplied <EM>getparyx</EM>. +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG>, <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG> +ncurses 6.6 2025-02-01 <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -119,6 +122,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF= <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_in_wch.3x.html b/doc/html/man/curs_in_wch.3x.html index 1ea5b63ec42b..6e8d9563402a 100644 --- a/doc/html/man/curs_in_wch.3x.html +++ b/doc/html/man/curs_in_wch.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2002-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,73 +27,82 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_in_wch.3x,v 1.31 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_in_wch.3x,v 1.44 2025/02/01 22:54:32 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_in_wch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_in_wch 3x 2025-02-01 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_in_wch 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_in_wch 3x 2025-02-01 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>in_wch</STRONG>, <STRONG>mvin_wch</STRONG>, <STRONG>mvwin_wch</STRONG>, <STRONG>win_wch</STRONG> - get a <EM>curses</EM> complex character + <STRONG>in_wch</STRONG>, <STRONG>win_wch</STRONG>, <STRONG>mvin_wch</STRONG>, <STRONG>mvwin_wch</STRONG> - get a <EM>curses</EM> complex character from a window </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>in_wch(cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>win_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>mvin_wch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwin_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>in_wch(cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>win_wch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvin_wch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwin_wch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These functions extract the complex character and rendition from the - current position in the named window into the <STRONG>cchar_t</STRONG> object referenced - by wch. + <STRONG>win_wch</STRONG> copies the <EM>curses</EM> complex character at the cursor position in + <EM>win</EM> into <EM>wch</EM>. Use <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG> to extract its character code, + attributes, and color pair identifier. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the + variants of this function. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - No errors are defined in X/Open Curses. This implementation checks for - null pointers, returns <STRONG>ERR</STRONG> in that case. Also, the <EM>mv</EM> routines check - for error moving the cursor, returning <STRONG>ERR</STRONG> in that case. Otherwise - they return <STRONG>OK</STRONG>. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. + + In <EM>ncurses</EM>, they return <STRONG>ERR</STRONG> if <EM>win</EM> is <EM>NULL</EM>. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that all of these routines may be macros. + <STRONG>in_wch</STRONG>, <STRONG>mvin_wch</STRONG>, and <STRONG>mvwin_wch</STRONG> may be implemented as macros. + + Unlike <STRONG><A HREF="curs_inch.3x.html">winch(3x)</A></STRONG>, <STRONG>win_wch</STRONG> and its variants store the value of the + retrieved character in an additional <EM>wch</EM> parameter instead of the + return value. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + X/Open Curses Issue 4 (1995) initially specified these functions. The + System V Interface Definition Version 4 of the same year specified a + function named <EM>winwch</EM> (and the usual variants). This was a later + addition to SVr4.<EM>x</EM>, not appearing in the first SVr4 (1989). It + differed from X/Open's later <EM>win</EM><STRONG>_</STRONG><EM>wch</EM> in that it returned a value of + type <EM>chtype</EM> instead of <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in + <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in its non-wide-character configuration. <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG> +ncurses 6.6 2025-02-01 <STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -103,6 +112,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF=" <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_in_wchstr.3x.html b/doc/html/man/curs_in_wchstr.3x.html index d7af18ddcfdf..52919fc8f48e 100644 --- a/doc/html/man/curs_in_wchstr.3x.html +++ b/doc/html/man/curs_in_wchstr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2002-2012,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_in_wchstr.3x,v 1.39 2024/04/20 21:24:19 tom Exp @ + * @Id: curs_in_wchstr.3x,v 1.56 2025/10/21 00:03:06 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_in_wchstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_in_wchstr 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_in_wchstr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_in_wchstr 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>in_wchstr</STRONG>, <STRONG>in_wchnstr</STRONG>, <STRONG>win_wchstr</STRONG>, <STRONG>win_wchnstr</STRONG>, <STRONG>mvin_wchstr</STRONG>, <STRONG>mvin_wchnstr</STRONG>, <STRONG>mvwin_wchstr</STRONG>, <STRONG>mvwin_wchnstr</STRONG> - get a <EM>curses</EM> complex @@ -55,70 +53,73 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>in_wchstr(cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>win_wchstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvin_wchstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwin_wchstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>in_wchstr(cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>win_wchstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvin_wchstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwin_wchstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>in_wchnstr(cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>win_wchnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvin_wchnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwin_wchnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>in_wchnstr(cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>win_wchnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvin_wchnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwin_wchnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wchstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>)</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These functions return an array of complex characters in <EM>wchstr</EM>, - starting at the current cursor position in the named window. - Attributes (rendition) are stored with the characters. - - The four functions with <EM>n</EM> as the last argument return a leading - substring at most <EM>n</EM> characters long (exclusive of the trailing zeroed - <STRONG>cchar_t</STRONG>. Transfer stops at the end of the current line, or when <EM>n</EM> - characters have been stored at the location referenced by <EM>wchstr</EM>. - - Constants defined in <STRONG><curses.h></STRONG> can be used with the <STRONG>&</STRONG> (logical AND) - operator to extract the character or the attribute alone from any - position in the <EM>wchstr</EM> [see <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG>]. + <STRONG>win_wchstr</STRONG> extracts a <EM>curses</EM> complex character string from a <EM>curses</EM> + window <EM>win</EM>, starting at the cursor and stopping at the end of the line, + and stores it in <EM>wchstr</EM>, terminating it with a wide null <EM>curses</EM> + character. <STRONG>win_wchnstr</STRONG> does the same, but copies at most <EM>n</EM> <EM>curses</EM> + complex characters from <EM>win</EM>. A negative <EM>n</EM> implies no limit; + <STRONG>win_wchnstr</STRONG> then works like <STRONG>win_wchstr</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the + variants of these functions. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Upon successful completion, these functions return <STRONG>OK</STRONG>. Otherwise, they - return <STRONG>ERR</STRONG>. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. + + In <EM>ncurses</EM>, these functions fail if - X/Open Curses defines no error conditions. This implementation returns - an error + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> if the <EM>win</EM> parameter is null or + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, or - <STRONG>o</STRONG> if the <EM>wchstr</EM> parameter is null. + <STRONG>o</STRONG> <EM>wchstr</EM> is a null pointer. - Functions prefixed with "mv" first perform cursor movement and fail if + Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All routines except <STRONG>win_wchnstr</STRONG> may be macros. + All of these functions except <STRONG>win_wchnstr</STRONG> may be implemented as macros. - Reading a line that overflows the array pointed to by <EM>wchstr</EM> with - <STRONG>in_wchstr</STRONG>, <STRONG>mvin_wchstr</STRONG>, <STRONG>mvwin_wchstr</STRONG> or <STRONG>win_wchstr</STRONG> causes undefined - results. Therefore, the use of <STRONG>in_wchnstr</STRONG>, <STRONG>mvin_wchnstr</STRONG>, - <STRONG>mvwin_wchnstr</STRONG>, or <STRONG>win_wchnstr</STRONG> is recommended. + Reading a line that overflows the array pointed to by <EM>wchstr</EM> and its + variants causes undefined results. Instead, use the <EM>n</EM>-infixed + functions with a positive <EM>n</EM> argument no larger than the size of the + buffer backing <EM>wchstr</EM>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses defines no error conditions. This implementation checks - for null pointers, returning <STRONG>ERR</STRONG> in that case. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + X/Open Curses Issue 4 (1995) initially specified these functions. The + System V Interface Definition Version 4 of the same year specified a + function named <EM>winwchstr</EM> (and the usual variants). This was a later + addition to SVr4.<EM>x</EM>, not appearing in the first SVr4 (1989). It + differed from X/Open's later <EM>win</EM><STRONG>_</STRONG><EM>wchstr</EM> in that it took an argument of + type pointer-to-<EM>chtype</EM> instead of pointer-to-<EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library + <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in its non-wide-character configuration. <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>, <STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -128,6 +129,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="cur <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_inch.3x.html b/doc/html/man/curs_inch.3x.html index 15bd134e9b76..512fe8aa4ca2 100644 --- a/doc/html/man/curs_inch.3x.html +++ b/doc/html/man/curs_inch.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_inch.3x,v 1.51 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_inch.3x,v 1.70 2025/02/15 19:36:03 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_inch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_inch 3x 2025-02-15 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_inch 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_inch 3x 2025-02-15 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>inch</STRONG>, <STRONG>winch</STRONG>, <STRONG>mvinch</STRONG>, <STRONG>mvwinch</STRONG> - get a <EM>curses</EM> character from a window @@ -55,92 +53,78 @@ <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> <STRONG>chtype</STRONG> <STRONG>inch(void);</STRONG> - <STRONG>chtype</STRONG> <STRONG>winch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> - + <STRONG>chtype</STRONG> <STRONG>winch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>);</STRONG> <STRONG>chtype</STRONG> <STRONG>mvinch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> - <STRONG>chtype</STRONG> <STRONG>mvwinch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> + <STRONG>chtype</STRONG> <STRONG>mvwinch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These routines return the character, of type <STRONG>chtype</STRONG>, at the current - position in the named window. If any attributes are set for that - position, their values are OR'ed into the value returned. Constants - defined in <STRONG><curses.h></STRONG> can be used with the <STRONG>&</STRONG> (logical AND) operator to - extract the character or attributes alone. - + <STRONG>winch</STRONG> returns the <EM>curses</EM> character, including its attributes and color + pair identifier, at the cursor position in the window <EM>win</EM>. Subsection + "Video Attributes" of <STRONG><A HREF="curs_attr.3x.html">attron(3x)</A></STRONG> explains how to extract these data + from a <EM>chtype</EM>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function. -</PRE><H3><a name="h3-Attributes">Attributes</a></H3><PRE> - The following bit masks may be AND-ed with characters returned by - <STRONG>winch</STRONG>. - <STRONG>Name</STRONG> <STRONG>Description</STRONG> - ------------------------------------------------------------------------ - <STRONG>A_CHARTEXT</STRONG> Extract character - <STRONG>A_ATTRIBUTES</STRONG> Extract attributes - <STRONG>A_COLOR</STRONG> Extract color pair information +</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. + In <EM>ncurses</EM>, they return <STRONG>ERR</STRONG> if <EM>win</EM> is <EM>NULL</EM>. -</PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. - The <STRONG>winch</STRONG> function does not return an error if the window contains - characters larger than 8-bits (255). Only the low-order 8 bits of the - character are used by <STRONG>winch</STRONG>. - </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that all of these routines may be macros. + <STRONG>inch</STRONG>, <STRONG>mvinch</STRONG>, and <STRONG>mvwinch</STRONG> may be implemented as macros. + These functions do not fail if the window contains cells of <EM>curses</EM> + complex characters; that is, if they contain characters with codes + wider than eight bits (or greater than 255 as an unsigned decimal + integer). They instead extract only the low-order eight bits of the + character code from the cell. -</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. - Very old systems (before standardization) provide a different function - with the same name: - - <STRONG>o</STRONG> The <STRONG>winch</STRONG> function was part of the original BSD curses library, - which stored a 7-bit character combined with the <EM>standout</EM> - attribute. - - In BSD curses, <STRONG>winch</STRONG> returned only the character (as an integer) - with the <EM>standout</EM> attribute removed. +</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - <STRONG>o</STRONG> System V curses added support for several video attributes which - could be combined with characters in the window. - Reflecting this improvement, the function was altered to return the - character combined with all video attributes in a <STRONG>chtype</STRONG> value. +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + The original <EM>curses</EM> in 4BSD (1980) defined <EM>winch</EM> as a macro accessing + the <EM>WINDOW</EM> structure member representing character cell data, at that + time a <EM>char</EM>, containing only a 7-bit ASCII character code and a + "standout" attribute bit, the only one the library supported. - X/Open Curses does not specify the size and layout of attributes, color - and character values in <STRONG>chtype</STRONG>; it is implementation-dependent. This - implementation uses 8 bits for character values. An application using - more bits, e.g., a Unicode value, should use the wide-character - equivalents to these functions. + SVr2 <EM>curses</EM> (1984) extended this approach, widening the character code + to eight bits and permitting several attributes to be combined with it + by storing them together in a <EM>chtype</EM>, an alias of <EM>unsigned</EM> <EM>short</EM>. + Because a macro was used, its value was not type-checked as a function + return value could have been. Goodheart documented SVr3 (1987) <EM>winch</EM> + as returning an <EM>int</EM>. SVr3.1's (1987) <EM>chtype</EM> became an alias of + <EM>unsigned</EM> <EM>long</EM>, using 16 bits for the character code and widening the + type in practical terms to 32 bits, as 64-bit Unix systems were not yet + in wide use, and fixed-width integral types would not be standard until + ISO C99. SVr3.2 (1988) added a 6-bit color pair identifier alongside + the attributes. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library + <STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in its wide-character configuration (<EM>ncursesw</EM>). <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG> +ncurses 6.6 2025-02-15 <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> <li><a href="#h2-NAME">NAME</a></li> <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> -<li><a href="#h2-DESCRIPTION">DESCRIPTION</a> -<ul> -<li><a href="#h3-Attributes">Attributes</a></li> -</ul> -</li> +<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_inchstr.3x.html b/doc/html/man/curs_inchstr.3x.html index 1eeb1b3a3c5e..362f541aed56 100644 --- a/doc/html/man/curs_inchstr.3x.html +++ b/doc/html/man/curs_inchstr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_inchstr.3x,v 1.45 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_inchstr.3x,v 1.65 2025/10/21 00:05:02 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_inchstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_inchstr 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_inchstr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_inchstr 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>inchstr</STRONG>, <STRONG>inchnstr</STRONG>, <STRONG>winchstr</STRONG>, <STRONG>winchnstr</STRONG>, <STRONG>mvinchstr</STRONG>, <STRONG>mvinchnstr</STRONG>, <STRONG>mvwinchstr</STRONG>, <STRONG>mvwinchnstr</STRONG> - get a <EM>curses</EM> character string from a window @@ -54,73 +52,85 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>inchstr(chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>inchnstr(chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>winchstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>winchnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>inchstr(chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>inchnstr(chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>winchstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>winchnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvinchstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvinchnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwinchstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwinchnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG><EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvinchstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvinchnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwinchstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwinchnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <STRONG>*</STRONG> <EM>chstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These routines return a NULL-terminated array of <STRONG>chtype</STRONG> quantities, - starting at the current cursor position in the named window and ending - at the right margin of the window. - - The four functions with <EM>n</EM> as the last argument, return a leading - substring at most <EM>n</EM> characters long (exclusive of the trailing - (chtype)0). Transfer stops at the end of the current line, or when <EM>n</EM> - characters have been stored at the location referenced by <EM>chstr</EM>. - - Constants defined in <STRONG><curses.h></STRONG> can be used with the <STRONG>&</STRONG> (logical AND) - operator to extract the character or the attribute alone from any - position in the <EM>chstr</EM> [see <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>]. + <STRONG>winchstr</STRONG> extracts a <EM>curses</EM> character string from a <EM>curses</EM> window <EM>win</EM>, + starting at the cursor and stopping at the end of the line, and stores + it in <EM>chstr</EM>, terminating it with a null <EM>curses</EM> character. <STRONG>winchnstr</STRONG> + does the same, but copies at most <EM>n</EM> <EM>curses</EM> characters from <EM>win</EM>. A + negative <EM>n</EM> implies no limit; <STRONG>winchnstr</STRONG> then works like <STRONG>winchstr</STRONG>. + <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All routines return the integer <STRONG>ERR</STRONG> upon failure and an integer value - other than <STRONG>ERR</STRONG> upon successful completion (the number of characters - retrieved, exclusive of the trailing 0). + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. + + In <EM>ncurses</EM>, these functions fail if - X/Open Curses defines no error conditions. This implementation returns - an error + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> if the <EM>win</EM> parameter is null or + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, or - <STRONG>o</STRONG> if the <EM>chstr</EM> parameter is null. + <STRONG>o</STRONG> <EM>chstr</EM> is a null pointer. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All routines except <STRONG>winchnstr</STRONG> may be macros. + All of these functions except <STRONG>winchnstr</STRONG> may be implemented as macros. + + Reading a line that overflows the array pointed to by <EM>chstr</EM> and its + variants causes undefined results. Instead, use the <EM>n</EM>-infixed + functions with a positive <EM>n</EM> argument no larger than the size of the + buffer backing <EM>chstr</EM>. - SVr4 does not document whether the result string is zero-terminated; it - does not document whether a length limit argument includes any trailing - 0; and it does not document the meaning of the return value. - Reading a line that overflows the array pointed to by <EM>chstr</EM> with - <STRONG>inchstr</STRONG>, <STRONG>mvinchstr</STRONG>, <STRONG>mvwinchstr</STRONG> or <STRONG>winchstr</STRONG> causes undefined results. - Therefore, the use of <STRONG>inchnstr</STRONG>, <STRONG>mvinchnstr</STRONG>, <STRONG>mvwinchnstr</STRONG>, or <STRONG>winchnstr</STRONG> - is recommended. +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>inchnstr</STRONG>, <STRONG>winchnstr</STRONG>, <STRONG>mvinchnstr</STRONG>, and <STRONG>mvwinchnstr</STRONG>'s acceptance of + negative <EM>n</EM> values is an <EM>ncurses</EM> extension. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. It is no more - specific than the SVr4 documentation on the trailing 0. It does - specify that the successful return of the functions is <STRONG>OK</STRONG>. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. It characterizes the strings stored by these + functions as containing "at most <EM>n</EM> elements" from a window, but does + not specify whether the string stored by these functions is null- + terminated. + + SVr4 does not document whether it null-terminates the <EM>curses</EM> character + string it stores in <EM>chstr</EM>, and does not document whether a trailing + null <EM>curses</EM> character counts toward the length limit <EM>n</EM>. + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG>, <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG> +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr3.1 (1987) introduced these functions. + + +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> + library in its wide-character configuration (<EM>ncursesw</EM>). + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -129,7 +139,9 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="c <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_initscr.3x.html b/doc/html/man/curs_initscr.3x.html index 778fc0016d1a..9ef40ac253ac 100644 --- a/doc/html/man/curs_initscr.3x.html +++ b/doc/html/man/curs_initscr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_initscr.3x,v 1.69 2024/04/20 21:24:19 tom Exp @ + * @Id: curs_initscr.3x,v 1.112 2025/08/23 22:41:44 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_initscr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_initscr 3x 2025-08-23 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_initscr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_initscr 3x 2025-08-23 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>initscr</STRONG>, <STRONG>newterm</STRONG>, <STRONG>endwin</STRONG>, <STRONG>isendwin</STRONG>, <STRONG>set_term</STRONG>, <STRONG>delscreen</STRONG> - initialize, manipulate, or tear down <EM>curses</EM> terminal interface @@ -54,252 +52,297 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*initscr(void);</STRONG> + <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>initscr(void);</STRONG> <STRONG>int</STRONG> <STRONG>endwin(void);</STRONG> <STRONG>bool</STRONG> <STRONG>isendwin(void);</STRONG> - <STRONG>SCREEN</STRONG> <STRONG>*newterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>type</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG><EM>outf</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG><EM>inf</EM><STRONG>);</STRONG> - <STRONG>SCREEN</STRONG> <STRONG>*set_term(SCREEN</STRONG> <STRONG>*</STRONG><EM>new</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>delscreen(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>SCREEN</STRONG> <STRONG>*</STRONG> <STRONG>newterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>type</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG> <EM>outf</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG> <EM>inf</EM><STRONG>);</STRONG> + <STRONG>SCREEN</STRONG> <STRONG>*</STRONG> <STRONG>set_term(SCREEN</STRONG> <STRONG>*</STRONG> <EM>new</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>delscreen(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> </PRE><H3><a name="h3-initscr">initscr</a></H3><PRE> - <STRONG>initscr</STRONG> is normally the first <STRONG>curses</STRONG> routine to call when initializing - a program. A few special routines sometimes need to be called before - it; these are <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG>, <STRONG>filter</STRONG>, <STRONG>ripoffline</STRONG>, <STRONG>use_env</STRONG>. For multiple- - terminal applications, <STRONG>newterm</STRONG> may be called before <STRONG>initscr</STRONG>. + <STRONG>initscr</STRONG> determines the terminal type and initializes the library's + <EM>SCREEN</EM>, <EM>WINDOW</EM>, and other data structures. It is normally the first + <EM>curses</EM> function call a program performs. However, an application with + unusual needs might employ a few other <EM>curses</EM> functions beforehand: + + <STRONG>o</STRONG> <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG> to set up soft-label keys; + + <STRONG>o</STRONG> <STRONG><A HREF="curs_util.3x.html">filter(3x)</A></STRONG> if the program is designed to operate in a process + pipeline; + + <STRONG>o</STRONG> <STRONG><A HREF="curs_kernel.3x.html">ripoffline(3x)</A></STRONG> to reserve up to five lines at the top and/or bottom + of the screen from management by <STRONG>stdscr</STRONG>, the standard <EM>curses</EM> + window; and + + <STRONG>o</STRONG> <STRONG><A HREF="curs_util.3x.html">use_env(3x)</A></STRONG> and/or <STRONG><A HREF="curs_util.3x.html">use_tioctl(3x)</A></STRONG> to configure use of the process + environment and operating system's terminal driver, respectively, + when determining the dimensions of the terminal display. + + Further, a <EM>curses</EM> program might call <STRONG>newterm</STRONG> prior to or instead of + <STRONG>initscr</STRONG> in two specialized cases described in its subsection below. - The initscr code determines the terminal type and initializes all - <STRONG>curses</STRONG> data structures. <STRONG>initscr</STRONG> also causes the first call to - <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> to clear the screen. If errors occur, <STRONG>initscr</STRONG> writes an - appropriate error message to standard error and exits; otherwise, a - pointer is returned to <STRONG>stdscr</STRONG>. + <STRONG>initscr</STRONG> causes the first <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> call to clear the screen. If + errors occur, <STRONG>initscr</STRONG> writes an appropriate diagnostic message to the + standard error stream and exits; otherwise, it returns a pointer to + <STRONG>stdscr</STRONG>. </PRE><H3><a name="h3-newterm">newterm</a></H3><PRE> - A program that outputs to more than one terminal should use the <STRONG>newterm</STRONG> - routine for each terminal instead of <STRONG>initscr</STRONG>. A program that needs to - inspect capabilities, so it can continue to run in a line-oriented mode - if the terminal cannot support a screen-oriented program, would also - use <STRONG>newterm</STRONG>. + An application that manages multiple terminals should call <STRONG>newterm</STRONG> once + for each such device <EM>instead</EM> of <STRONG>initscr</STRONG>. <STRONG>newterm</STRONG>'s arguments are - The routine <STRONG>newterm</STRONG> should be called once for each terminal. It - returns a variable of type <EM>SCREEN</EM> <EM>*</EM> which should be saved as a - reference to that terminal. <STRONG>newterm</STRONG>'s arguments are + <STRONG>o</STRONG> the <EM>type</EM> of the associated terminal, or a null pointer to use the + <EM>TERM</EM> environment variable; - <STRONG>o</STRONG> the <EM>type</EM> of the terminal to be used in place of <STRONG>$TERM</STRONG>, + <STRONG>o</STRONG> an output stream <EM>outf</EM> connected to the terminal; and - <STRONG>o</STRONG> an output stream connected to the terminal, and + <STRONG>o</STRONG> an input stream <EM>inf</EM> connected to the terminal. - <STRONG>o</STRONG> an input stream connected to the terminal + <STRONG>newterm</STRONG> returns a variable of pointer-to-<EM>SCREEN</EM> type, which should be + saved for later use with <STRONG>set_term</STRONG> and <STRONG>delscreen</STRONG>. - If the <EM>type</EM> parameter is <STRONG>NULL</STRONG>, <STRONG>$TERM</STRONG> will be used. + <STRONG>newterm</STRONG> passes the file descriptor of the output stream to the <EM>terminfo</EM> + function <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>, which returns a pointer to a <EM>TERMINAL</EM> structure + that <STRONG>newterm</STRONG> stores in the <EM>SCREEN</EM> it returns to the application. - The file descriptor of the output stream is passed to <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>, - which returns a pointer to a <EM>TERMINAL</EM> structure. <STRONG>newterm</STRONG>'s return - value holds a pointer to the <EM>TERMINAL</EM> structure. + An application that needs to inspect a terminal type's capabilities, so + that it can continue to run in a line-oriented mode if the terminal + type does not support capabilities the application demands, would also + use <STRONG>newterm</STRONG>. If at most one terminal connection is needed, the + programmer could perform such a capability test, decide the mode in + which to operate, then call <STRONG>delscreen</STRONG> on the pointer returned by + <STRONG>newterm</STRONG>, and proceed with either <STRONG>initscr</STRONG> or a non-<EM>curses</EM> interface. </PRE><H3><a name="h3-endwin">endwin</a></H3><PRE> - The program must also call <STRONG>endwin</STRONG> for each terminal being used before - exiting from <STRONG>curses</STRONG>. If <STRONG>newterm</STRONG> is called more than once for the same + The program must also call <STRONG>endwin</STRONG> for each terminal being used before + exiting from <EM>curses</EM>. If <STRONG>newterm</STRONG> is called more than once for the same terminal, the first terminal referred to must be the last one for which <STRONG>endwin</STRONG> is called. - A program should always call <STRONG>endwin</STRONG> before exiting or escaping from - <STRONG>curses</STRONG> mode temporarily. This routine + A program should always call <STRONG>endwin</STRONG> before exiting the application or + temporarily suspending <EM>curses</EM>'s management of the terminal. <STRONG>endwin</STRONG>: - <STRONG>o</STRONG> resets colors to correspond with the default color pair 0, + <STRONG>o</STRONG> (if <STRONG><A HREF="curs_color.3x.html">start_color(3x)</A></STRONG> has been called) resets the terminal's + foreground and background colors to correspond with those of color + pair 0 (the default pair), <STRONG>o</STRONG> moves the cursor to the lower left-hand corner of the screen, - <STRONG>o</STRONG> clears the remainder of the line so that it uses the default - colors, + <STRONG>o</STRONG> (if <STRONG><A HREF="curs_color.3x.html">start_color(3x)</A></STRONG> has been called) restores the default color + pair, + + <STRONG>o</STRONG> clears the line, <STRONG>o</STRONG> sets the cursor to normal visibility (see <STRONG><A HREF="curs_kernel.3x.html">curs_set(3x)</A></STRONG>), - <STRONG>o</STRONG> stops cursor-addressing mode using the <EM>exit</EM><STRONG>_</STRONG><EM>ca</EM><STRONG>_</STRONG><EM>mode</EM> terminal - capability, + <STRONG>o</STRONG> if applicable, stops cursor-addressing mode using the <STRONG>exit_ca_mode</STRONG> + (<STRONG>rmcup</STRONG>) terminal capability, and - <STRONG>o</STRONG> restores tty modes (see <STRONG><A HREF="curs_kernel.3x.html">reset_shell_mode(3x)</A></STRONG>). + <STRONG>o</STRONG> restores terminal modes (see <STRONG><A HREF="curs_kernel.3x.html">reset_shell_mode(3x)</A></STRONG>). - Calling <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> or <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> after a temporary escape causes the - program to resume visual mode. + Calling <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> or <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> after a temporary suspension causes + <EM>curses</EM> to resume managing the terminal. </PRE><H3><a name="h3-isendwin">isendwin</a></H3><PRE> - The <STRONG>isendwin</STRONG> routine returns <STRONG>TRUE</STRONG> if <STRONG>endwin</STRONG> has been called without any - subsequent calls to <STRONG>wrefresh</STRONG>, and <STRONG>FALSE</STRONG> otherwise. + <STRONG>isendwin</STRONG> returns <STRONG>TRUE</STRONG> if <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG> has not been called since the + most recent <STRONG>endwin</STRONG> call, and <STRONG>FALSE</STRONG> otherwise. </PRE><H3><a name="h3-set_term">set_term</a></H3><PRE> - The <STRONG>set_term</STRONG> routine is used to switch between different terminals. - The screen reference <EM>new</EM> becomes the new current terminal. The - previous terminal is returned by the routine. This is the only routine - which manipulates <EM>SCREEN</EM> pointers; all other routines affect only the - current terminal. + <STRONG>set_term</STRONG> re-orients the <EM>curses</EM> library's operations to another terminal + when the application has arranged to manage more than one with <STRONG>newterm</STRONG>. + <STRONG>set_term</STRONG> expects a <EM>SCREEN</EM> pointer previously returned by <STRONG>newterm</STRONG> as an + argument, and returns the previous one. <STRONG>set_term</STRONG> is the only standard + <EM>curses</EM> API function that manipulates <EM>SCREEN</EM> pointers; all others affect + only the current terminal (but see <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>). </PRE><H3><a name="h3-delscreen">delscreen</a></H3><PRE> - The <STRONG>delscreen</STRONG> routine frees storage associated with the <EM>SCREEN</EM> data - structure. The <STRONG>endwin</STRONG> routine does not do this, so <STRONG>delscreen</STRONG> should be - called after <STRONG>endwin</STRONG> if a particular <EM>SCREEN</EM> is no longer needed. + <STRONG>delscreen</STRONG> frees the storage backing the supplied <EM>SCREEN</EM> pointer + argument. <STRONG>endwin</STRONG> does not, so that an application can resume managing + a terminal with <EM>curses</EM> after a (possibly conditional or temporary) + suspension; see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>. Use <STRONG>delscreen</STRONG> after <STRONG>endwin</STRONG> when the + application has no more need of a terminal device but will not soon + exit. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - <STRONG>endwin</STRONG> returns the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon successful - completion. + <STRONG>delscreen</STRONG> returns no value. <STRONG>endwin</STRONG> returns <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on + failure. <STRONG>isendwin</STRONG> returns <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG> as described above. + + In <EM>ncurses</EM>, + + <STRONG>o</STRONG> <STRONG>endwin</STRONG> returns <STRONG>ERR</STRONG> if + + <STRONG>o</STRONG> the terminal was not initialized, + + <STRONG>o</STRONG> it is called more than once without updating the screen, or + + <STRONG>o</STRONG> its call of <STRONG><A HREF="curs_kernel.3x.html">reset_shell_mode(3x)</A></STRONG> returns <STRONG>ERR</STRONG>; and - Routines that return pointers always return <STRONG>NULL</STRONG> on error. + <STRONG>o</STRONG> <STRONG>newterm</STRONG> returns <STRONG>ERR</STRONG> if it cannot allocate storage for the <EM>SCREEN</EM> + structure or the <EM>WINDOW</EM> structures automatically associated with + it: <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>, and <STRONG>stdscr</STRONG>. - X/Open defines no error conditions. In this implementation + Functions that return pointers return null pointers on error. In + <EM>ncurses</EM>, <STRONG>set_term</STRONG> does not fail, and <STRONG>initscr</STRONG> exits the application if + it does not operate successfully. - <STRONG>o</STRONG> <STRONG>endwin</STRONG> returns an error if - <STRONG>o</STRONG> the terminal was not initialized, or +</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> + <EM>ncurses</EM> establishes signal handlers when a function that initializes a + <EM>SCREEN</EM>, either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>, is first called. Applications that + wish to handle the following signals themselves should set up their + corresponding handlers <EM>after</EM> initializing the screen. - <STRONG>o</STRONG> <STRONG>endwin</STRONG> is called more than once without updating the screen, or + <EM>SIGINT</EM> <EM>ncurses</EM>'s handler <EM>attempts</EM> to clean up the screen on exit. + Although it <EM>usually</EM> works as expected, there are limitations. - <STRONG>o</STRONG> <STRONG><A HREF="curs_kernel.3x.html">reset_shell_mode(3x)</A></STRONG> returns an error. + <STRONG>o</STRONG> Walking the <EM>SCREEN</EM> list is unsafe, since all list management + is done without any signal blocking. - <STRONG>o</STRONG> <STRONG>newterm</STRONG> returns an error if it cannot allocate the data structures - for the screen, or for the top-level windows within the screen, - i.e., <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>, or <STRONG>stdscr</STRONG>. + <STRONG>o</STRONG> When an application has been built with the <STRONG>_</STRONG><EM>REENTRANT</EM> macro + defined (and corresponding system support), <STRONG>set_term</STRONG> uses + functions that could deadlock or misbehave in other ways. - <STRONG>o</STRONG> <STRONG>set_term</STRONG> returns no error. + <STRONG>o</STRONG> <STRONG>endwin</STRONG> calls other functions, many of which use <STRONG>stdio(3)</STRONG> or + other library functions that are clearly unsafe. + + <EM>SIGTERM</EM> + <EM>ncurses</EM> uses the same handler as for <EM>SIGINT</EM>, with the same + limitations. It is not mentioned in X/Open Curses, but is more + suitable for this purpose than <EM>SIGQUIT</EM> (which is used in + debugging). + + <EM>SIGTSTP</EM> + <EM>ncurses</EM>'s handler manages the terminal-generated stop signal, + used in job control. When resuming the process, <EM>ncurses</EM> + discards pending input with <STRONG><A HREF="curs_util.3x.html">flushinp(3x)</A></STRONG> and repaints the + screen, assuming that it has been completely altered. It also + updates the saved terminal modes with <STRONG><A HREF="curs_kernel.3x.html">def_shell_mode(3x)</A></STRONG>. + + <EM>SIGWINCH</EM> + <EM>ncurses</EM> handles changes to the terminal's window size, a + phenomenon ignored in standardization efforts. It sets a + (signal-safe) variable that is later tested by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> and + <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG>. + + <STRONG>o</STRONG> <STRONG>wgetch</STRONG> returns the key code <STRONG>KEY_RESIZE</STRONG>. + + <STRONG>o</STRONG> <STRONG>wget_wch</STRONG> returns <STRONG>KEY_CODE_YES</STRONG> and sets its <EM>wch</EM> parameter to + <STRONG>KEY_RESIZE</STRONG>. + + At the same time, <EM>ncurses</EM> calls <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> to adjust the + standard screen <STRONG>stdscr</STRONG> and update global variables such as <STRONG>LINES</STRONG> + and <STRONG>COLS</STRONG>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions were described in X/Open Curses, Issue 4. As of 2015, - the current document is X/Open Curses, Issue 7. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. </PRE><H3><a name="h3-Differences">Differences</a></H3><PRE> - X/Open Curses specifies that portable applications must not call - <STRONG>initscr</STRONG> more than once: + X/Open Curses specifies that portable applications must not call + <EM>initscr</EM> more than once. - <STRONG>o</STRONG> The portable way to use <STRONG>initscr</STRONG> is once only, using <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> to - restore the screen after <STRONG>endwin</STRONG>. + <STRONG>o</STRONG> The portable way to use <EM>initscr</EM> is once only, using <EM>refresh</EM> to + restore the screen after <EM>endwin</EM>. - <STRONG>o</STRONG> This implementation allows using <STRONG>initscr</STRONG> after <STRONG>endwin</STRONG>. + <STRONG>o</STRONG> <EM>ncurses</EM> permits use of <EM>initscr</EM> after <EM>endwin</EM>. - Old versions of curses, e.g., BSD 4.4, would return a null pointer from - <STRONG>initscr</STRONG> when an error is detected, rather than exiting. It is safe but - redundant to check the return value of <STRONG>initscr</STRONG> in X/Open Curses. + <EM>initscr</EM> in BSD, from its inception (1980) through the Net/2 release + (1991) returned <EM>ERR</EM> cast to a <EM>WINDOW</EM> pointer when detecting an error. + 4.4BSD (1995) instead returned a null pointer. Neither exited the + application. It is safe but redundant to check the return value of + <EM>initscr</EM> in X/Open Curses. - Calling <STRONG>endwin</STRONG> does not dispose of the memory allocated in <STRONG>initscr</STRONG> or - <STRONG>newterm</STRONG>. Deleting a <EM>SCREEN</EM> provides a way to do this: + Calling <EM>endwin</EM> does not dispose of the memory allocated by <EM>initscr</EM> or + <EM>newterm</EM>. Deleting a <EM>SCREEN</EM> provides a way to do this. - <STRONG>o</STRONG> X/Open Curses does not say what happens to <EM>WINDOW</EM>s when <STRONG>delscreen</STRONG> - "frees storage associated with the <EM>SCREEN</EM>" nor does the SVr4 - documentation help, adding that it should be called after <STRONG>endwin</STRONG> if + <STRONG>o</STRONG> X/Open Curses does not say what happens to <EM>WINDOW</EM>s when <EM>delscreen</EM> + "frees storage associated with the <EM>SCREEN</EM>" nor does the SVr4 + documentation help, adding that it should be called after <EM>endwin</EM> if a <EM>SCREEN</EM> is no longer needed. - <STRONG>o</STRONG> However, <EM>WINDOW</EM>s are implicitly associated with a <EM>SCREEN</EM>. so that - it is reasonable to expect <STRONG>delscreen</STRONG> to deal with these. + <STRONG>o</STRONG> However, every <EM>WINDOW</EM> is implicitly associated with a <EM>SCREEN</EM>, so it + is reasonable to expect <EM>delscreen</EM> to dispose of them. - <STRONG>o</STRONG> SVr4 curses deletes the standard <EM>WINDOW</EM> structures <STRONG>stdscr</STRONG> and - <STRONG>curscr</STRONG> as well as a work area <STRONG>newscr</STRONG>. SVr4 curses ignores other - windows. + <STRONG>o</STRONG> SVr4 deletes the standard <EM>WINDOW</EM> structures <EM>stdscr</EM> and <EM>curscr</EM> as + well as a work area <EM>newscr</EM>. It ignores other windows. <STRONG>o</STRONG> Since version 4.0 (1996), <EM>ncurses</EM> has maintained a list of all windows for each screen, using that information to delete those - windows when <STRONG>delscreen</STRONG> is called. - - <STRONG>o</STRONG> NetBSD copied this feature of <EM>ncurses</EM> in 2001. PDCurses follows - the SVr4 model, deleting only the standard <EM>WINDOW</EM> structures. + windows when <EM>delscreen</EM> is called. + <STRONG>o</STRONG> NetBSD copied this feature of <EM>ncurses</EM> in 2001. <EM>PDCurses</EM> follows + the SVr4 model, deleting only the standard <EM>WINDOW</EM> structures and + <EM>newscr</EM>. -</PRE><H3><a name="h3-High-level-versus-Low-level">High-level versus Low-level</a></H3><PRE> - Different implementations may disagree regarding the level of some - functions. For example, <EM>SCREEN</EM> (returned by <STRONG>newterm</STRONG>) and <EM>TERMINAL</EM> - (returned by <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>) hold file descriptors for the output - stream. If an application switches screens using <STRONG>set_term</STRONG>, or switches - terminals using <STRONG><A HREF="curs_terminfo.3x.html">set_curterm(3x)</A></STRONG>, applications which use the output file - descriptor can have different behavior depending on which structure - holds the corresponding descriptor. - For example +</PRE><H3><a name="h3-High-level-versus-Low-level-Functions">High-level versus Low-level Functions</a></H3><PRE> + Implementations disagree regarding the level of abstraction applicable + to a function or property. For example, <EM>SCREEN</EM> (returned by <EM>newterm</EM>) + and <EM>TERMINAL</EM> (returned by <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>) hold file descriptors for the + output stream. If an application switches screens using <EM>set</EM><STRONG>_</STRONG><EM>term</EM>, or + switches terminals using <STRONG><A HREF="curs_terminfo.3x.html">set_curterm(3x)</A></STRONG>, applications using the output + file descriptor can behave differently depending on the structure + holding the corresponding descriptor. - <STRONG>o</STRONG> NetBSD's <STRONG><A HREF="curs_termattrs.3x.html">baudrate(3x)</A></STRONG> function uses the descriptor in <EM>TERMINAL</EM>. + <STRONG>o</STRONG> NetBSD's <EM>baudrate</EM> function uses the descriptor in <EM>TERMINAL</EM>. <EM>ncurses</EM> and SVr4 use the descriptor in <EM>SCREEN</EM>. <STRONG>o</STRONG> NetBSD and <EM>ncurses</EM> use the descriptor in <EM>TERMINAL</EM> for terminal I/O - modes, e.g., <STRONG><A HREF="curs_kernel.3x.html">def_shell_mode(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">def_prog_mode(3x)</A></STRONG>. SVr4 curses - uses the descriptor in <EM>SCREEN</EM>. + modes, e.g., <STRONG><A HREF="curs_kernel.3x.html">def_shell_mode(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">def_prog_mode(3x)</A></STRONG>. SVr4 uses the + descriptor in <EM>SCREEN</EM>. - <STRONG>Unset</STRONG> <EM>TERM</EM> <STRONG>Variable</STRONG> - If the <EM>TERM</EM> variable is missing or empty, <STRONG>initscr</STRONG> uses the value - "unknown", which normally corresponds to a terminal entry with the - <EM>generic</EM> (<EM>gn</EM>) capability. Generic entries are detected by <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> - and cannot be used for full-screen operation. Other implementations - may handle a missing/empty <EM>TERM</EM> variable differently. + +</PRE><H3><a name="h3-Unset-TERM-Environment-Variable">Unset TERM Environment Variable</a></H3><PRE> + If the <EM>TERM</EM> variable is not set in the environment or has an empty + value, <EM>initscr</EM> uses the value "unknown", which normally corresponds to + a terminal entry with the <STRONG>generic</STRONG> (<STRONG>gn</STRONG>) capability. Generic entries are + detected by <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> and cannot be used for full-screen operation. + Other implementations may handle a missing or empty <EM>TERM</EM> variable + differently. </PRE><H3><a name="h3-Signal-Handlers">Signal Handlers</a></H3><PRE> - Quoting from X/Open Curses Issue 7, section 3.1.1: + Quoting X/Open Curses Issue 7, section 3.1.1: - Curses implementations may provide for special handling of the - SIGINT, SIGQUIT, and SIGTSTP signals if their disposition is - SIG_DFL at the time <EM>initscr</EM> is called... + Curses implementations may provide for special handling of the + SIGINT, SIGQUIT, and SIGTSTP signals if their disposition is + SIG_DFL at the time <EM>initscr</EM>() is called... - Any special handling for these signals may remain in effect for + Any special handling for these signals may remain in effect for the life of the process or until the process changes the disposition of the signal. - None of the Curses functions are required to be safe with respect + None of the Curses functions are required to be safe with respect to signals... - This implementation establishes signal handlers during initialization, - e.g., <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. Applications which must handle these signals - should set up the corresponding handlers <EM>after</EM> initializing the - library: - - <STRONG>SIGINT</STRONG> - The handler <EM>attempts</EM> to clean up the screen on exit. Although it - <EM>usually</EM> works as expected, there are limitations: - - <STRONG>o</STRONG> Walking the <EM>SCREEN</EM> list is unsafe, since all list management - is done without any signal blocking. + Section "NOTES" above discusses <EM>ncurses</EM>'s signal handlers. - <STRONG>o</STRONG> On systems which have <STRONG>REENTRANT</STRONG> turned on, <STRONG>set_term</STRONG> uses - functions which could deadlock or misbehave in other ways. - <STRONG>o</STRONG> <STRONG>endwin</STRONG> calls other functions, many of which use <STRONG>stdio(3)</STRONG> or - other library functions which are clearly unsafe. +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced <EM>initscr</EM> and <EM>endwin</EM>. - <STRONG>SIGTERM</STRONG> - This uses the same handler as <STRONG>SIGINT</STRONG>, with the same limitations. - It is not mentioned in X/Open Curses, but is more suitable for - this purpose than <STRONG>SIGQUIT</STRONG> (which is used in debugging). + SVr2 (1984) added <EM>newterm</EM> and <EM>set</EM><STRONG>_</STRONG><EM>term</EM>. - <STRONG>SIGTSTP</STRONG> - This handles the <EM>stop</EM> signal, used in job control. When resuming - the process, this implementation discards pending input with - <STRONG><A HREF="curs_util.3x.html">flushinp(3x)</A></STRONG>, and repaints the screen assuming that it has been - completely altered. It also updates the saved terminal modes with - <STRONG><A HREF="curs_kernel.3x.html">def_shell_mode(3x)</A></STRONG>. - - <STRONG>SIGWINCH</STRONG> - This handles the window-size changes which were ignored in the - standardization efforts. The handler sets a (signal-safe) - variable which is later tested in <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>. If <STRONG>keypad</STRONG> has been - enabled for the corresponding window, <STRONG>wgetch</STRONG> returns the key - symbol <STRONG>KEY_RESIZE</STRONG>. At the same time, <STRONG>wgetch</STRONG> calls <STRONG>resizeterm</STRONG> to - adjust the standard screen <STRONG>stdscr</STRONG>, and update other data such as - <STRONG>LINES</STRONG> and <STRONG>COLS</STRONG>. + SVr3.1 (1987) supplied <EM>delscreen</EM> and <EM>isendwin</EM>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> +ncurses 6.6 2025-08-23 <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -316,13 +359,16 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="c </ul> </li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> +<li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a> <ul> <li><a href="#h3-Differences">Differences</a></li> -<li><a href="#h3-High-level-versus-Low-level">High-level versus Low-level</a></li> +<li><a href="#h3-High-level-versus-Low-level-Functions">High-level versus Low-level Functions</a></li> +<li><a href="#h3-Unset-TERM-Environment-Variable">Unset TERM Environment Variable</a></li> <li><a href="#h3-Signal-Handlers">Signal Handlers</a></li> </ul> </li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_inopts.3x.html b/doc/html/man/curs_inopts.3x.html index 149b2b82be28..8b3c155a23db 100644 --- a/doc/html/man/curs_inopts.3x.html +++ b/doc/html/man/curs_inopts.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_inopts.3x,v 1.66 2024/04/13 22:20:29 tom Exp @ + * @Id: curs_inopts.3x,v 1.116 2025/10/04 20:15:02 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_inopts 3x 2024-04-13 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_inopts 3x 2025-10-04 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_inopts 3x 2024-04-13 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_inopts 3x 2025-10-04 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>cbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>is_cbreak</STRONG>, <STRONG>is_echo</STRONG>, <STRONG>is_nl</STRONG>, <STRONG>is_raw</STRONG>, <STRONG>keypad</STRONG>, <STRONG>meta</STRONG>, <STRONG>nl</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>noecho</STRONG>, <STRONG>nonl</STRONG>, <STRONG>noqiflush</STRONG>, <STRONG>noraw</STRONG>, @@ -63,24 +61,24 @@ <STRONG>int</STRONG> <STRONG>echo(void);</STRONG> <STRONG>int</STRONG> <STRONG>noecho(void);</STRONG> - <STRONG>int</STRONG> <STRONG>intrflush(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>keypad(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>meta(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>nodelay(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>notimeout(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>intrflush(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM> <EM>/*</EM> <EM>ignored</EM> <EM>*/</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>keypad(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>meta(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM> <EM>/*</EM> <EM>ignored</EM> <EM>*/</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>nodelay(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>notimeout(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>nl(void);</STRONG> <STRONG>int</STRONG> <STRONG>nonl(void);</STRONG> - <STRONG>int</STRONG> <STRONG>raw(void);</STRONG> - <STRONG>int</STRONG> <STRONG>noraw(void);</STRONG> - <STRONG>void</STRONG> <STRONG>qiflush(void);</STRONG> <STRONG>void</STRONG> <STRONG>noqiflush(void);</STRONG> + <STRONG>int</STRONG> <STRONG>raw(void);</STRONG> + <STRONG>int</STRONG> <STRONG>noraw(void);</STRONG> + <STRONG>int</STRONG> <STRONG>halfdelay(int</STRONG> <EM>tenths</EM><STRONG>);</STRONG> <STRONG>void</STRONG> <STRONG>timeout(int</STRONG> <EM>delay</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>wtimeout(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>delay</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>wtimeout(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>delay</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>typeahead(int</STRONG> <EM>fd</EM><STRONG>);</STRONG> @@ -92,174 +90,225 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - <EM>ncurses</EM> provides several functions that let an application change the - way input from the terminal is handled. Some are global, applying to - all windows. Others apply only to a specific window. Window-specific - settings are not automatically applied to new or derived windows. An - application must apply these to each window if the same behavior is - desired. + <EM>curses</EM> offers configurable parameters permitting an application to + control the handling of input from the terminal. Some, such as those + affecting the terminal's <EM>mode</EM> or line discipline, are global, applying + to all windows; others apply only to a specific window. The library + does not automatically apply such parameters to new or derived windows; + an application must configure each window for the desired behavior. + Some descriptions below make reference to an <EM>input</EM> <EM>character</EM> <EM>reading</EM> + <EM>function</EM>: this is <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> in the non-wide character <EM>curses</EM> API and + <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG> in the wide character API. In addition to the variant + forms of these described in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, the <EM>curses</EM> functions + <STRONG><A HREF="curs_getstr.3x.html">wgetstr(3x)</A></STRONG> and <STRONG><A HREF="curs_get_wstr.3x.html">wget_wstr(3x)</A></STRONG> and their own variants call the + appropriate input character reading function. -</PRE><H3><a name="h3-cbreak_nocbreak">cbreak, nocbreak</a></H3><PRE> - Normally, the terminal driver buffers typed characters until a newline - or carriage return is typed. The <STRONG>cbreak</STRONG> routine disables line - buffering and erase/kill character-processing (interrupt and flow - control characters are unaffected), making characters typed by the user - immediately available to the program. The <STRONG>nocbreak</STRONG> routine returns the - terminal to normal (cooked) mode. - Initially the terminal may or may not be in <STRONG>cbreak</STRONG> mode, as the mode is - inherited; therefore, a program should call <STRONG>cbreak</STRONG> or <STRONG>nocbreak</STRONG> - explicitly. Most interactive programs using <EM>curses</EM> set the <STRONG>cbreak</STRONG> - mode. Note that <STRONG>cbreak</STRONG> overrides <STRONG>raw</STRONG>. [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a - discussion of how these routines interact with <STRONG>echo</STRONG> and <STRONG>noecho</STRONG>.] +</PRE><H3><a name="h3-cbreak_nocbreak">cbreak, nocbreak</a></H3><PRE> + Normally, the terminal driver buffers typed characters, not delivering + them to an application until a line feed or carriage return is typed. + This canonical ("cooked") line discipline also supports software flow + control, simple line editing functions (character and word erase, and + whole-line erasure or "kill"), and job control. <STRONG>cbreak</STRONG> configures the + terminal in <EM>cbreak</EM> <EM>mode</EM>, which disables line buffering and erase and + kill character processing -- the interrupt, quit, suspend, and flow + control characters are unaffected -- and makes characters typed by the + user immediately available to the program. <STRONG>nocbreak</STRONG> restores canonical + ("cooked") mode. + + The state of the terminal is unknown to a <EM>curses</EM> application when it + starts; therefore, a program should call <STRONG>cbreak</STRONG> or <STRONG>nocbreak</STRONG> explicitly. + Most interactive programs using <EM>curses</EM> set cbreak mode. Calling <STRONG>cbreak</STRONG> + overrides <STRONG>raw</STRONG>. The man page for the input character reading function + discusses how <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG> interact with <STRONG>echo</STRONG> and <STRONG>noecho</STRONG>. </PRE><H3><a name="h3-echo_noecho">echo, noecho</a></H3><PRE> - The <STRONG>echo</STRONG> and <STRONG>noecho</STRONG> routines control whether characters typed by the - user are echoed by <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG> as they are typed. Echoing by the - terminal driver is always disabled, but initially <STRONG>getch</STRONG> is in echo - mode, so characters typed are echoed. Authors of most interactive - programs prefer to do their own echoing in a controlled area of the - screen, or not to echo at all, so they disable echoing by calling - <STRONG>noecho</STRONG>. [See <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> for a discussion of how these routines - interact with <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG>.] + <STRONG>echo</STRONG> and <STRONG>noecho</STRONG> determine whether characters typed by the user are + written to the <EM>curses</EM> window by the input character reading function as + they are typed. <EM>curses</EM> always disables the terminal driver's own + echoing. By default, a <EM>curses</EM> screen's echo option is set. Authors of + most interactive programs prefer to do their own echoing in a + controlled area of the screen, or not to echo at all, so they call + <STRONG>noecho</STRONG>. The man page for the input character reading function + discusses how <STRONG>echo</STRONG> and <STRONG>noecho</STRONG> interact with <STRONG>cbreak</STRONG> and <STRONG>nocbreak</STRONG>. </PRE><H3><a name="h3-halfdelay">halfdelay</a></H3><PRE> - The <STRONG>halfdelay</STRONG> routine is used for half-delay mode, which is similar to - <STRONG>cbreak</STRONG> mode in that characters typed by the user are immediately - available to the program. However, after blocking for <EM>tenths</EM> tenths of - seconds, <STRONG>ERR</STRONG> is returned if nothing has been typed. The value of - <EM>tenths</EM> must be a number between 1 and 255. Use <STRONG>nocbreak</STRONG> to leave half- + <STRONG>halfdelay</STRONG> configures <EM>half-delay</EM> <EM>mode</EM>, which is similar to cbreak mode + in that characters typed by the user are immediately available to the + program. However, after blocking for <EM>tenths</EM> tenth-seconds, an input + character reading function returns <STRONG>ERR</STRONG> if no input is pending. The + value of <EM>tenths</EM> must be between 1 and 255. Use <STRONG>nocbreak</STRONG> to leave half- delay mode. </PRE><H3><a name="h3-intrflush">intrflush</a></H3><PRE> - If the <STRONG>intrflush</STRONG> option is enabled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), and an interrupt key - is pressed on the keyboard (interrupt, break, quit), all output in the - terminal driver queue is flushed, giving the effect of faster response - to the interrupt, but causing <EM>curses</EM> to have the wrong idea of what is - on the screen. Disabling the option (<EM>bf</EM> is <STRONG>FALSE</STRONG>), prevents the flush. - The default for the option is inherited from the terminal driver - settings. The <EM>win</EM> argument is ignored. + <STRONG>intrflush</STRONG> calls <STRONG>qiflush</STRONG> (see below) if <EM>bf</EM> is <STRONG>TRUE</STRONG>, and <STRONG>noqiflush</STRONG> if <EM>bf</EM> + is <STRONG>FALSE</STRONG>. It ignores its <EM>win</EM> argument. </PRE><H3><a name="h3-keypad">keypad</a></H3><PRE> - The <STRONG>keypad</STRONG> option enables the keypad of the user's terminal. If - enabled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the user can press a function key (such as an - arrow key) and <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> returns a single value representing the - function key, as in <STRONG>KEY_LEFT</STRONG>. If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <EM>curses</EM> does - not treat function keys specially and the program has to interpret the - escape sequences itself. If the keypad in the terminal can be turned - on (made to transmit) and off (made to work locally), turning on this - option causes the terminal keypad to be turned on when <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> is - called. The default value for keypad is <STRONG>FALSE</STRONG>. + <STRONG>keypad</STRONG> enables recognition of a terminal's function keys. If enabled + (<EM>bf</EM> is <STRONG>TRUE</STRONG>) then when an input character reading function reads ESC, + it waits for further input corresponding to an escape sequence defined + by the terminal type description. If a valid sequence populates the + input stream, the input character reading function returns a value + representing the function key, such as <STRONG>KEY_LEFT</STRONG>. (Wide-character API + users: <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG> returns <STRONG>KEY_CODE_YES</STRONG> to indicate the availability + of a function key code in its <EM>wch</EM> parameter.) If the sequence is + invalid, the input character reading function returns only its last + character. If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <EM>curses</EM> does not treat function + keys specially and the program has to interpret escape sequences + itself. If the terminal type description defines the <STRONG>keypad_local</STRONG> + (<STRONG>rmkx</STRONG>) and <STRONG>keypad_xmit</STRONG> (<STRONG>smkx</STRONG>) capabilities, enabling a window's keypad + mode sets the terminal's keypad to transmit, and disabling keypad mode + sets the terminal's keypad to work locally. By default, a window's + keypad mode is off. </PRE><H3><a name="h3-meta">meta</a></H3><PRE> - Initially, whether the terminal returns 7 or 8 significant bits on - input depends on the control mode of the terminal driver [see - <STRONG>termios(3)</STRONG>]. To force 8 bits to be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>); - this is equivalent, under POSIX, to setting the CS8 flag on the - terminal. To force 7 bits to be returned, invoke <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>FALSE</STRONG>); - this is equivalent, under POSIX, to setting the CS7 flag on the - terminal. The window argument, <EM>win</EM>, is always ignored. If the - terminfo capabilities <STRONG>smm</STRONG> (meta_on) and <STRONG>rmm</STRONG> (meta_off) are defined for - the terminal, <STRONG>smm</STRONG> is sent to the terminal when <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>TRUE</STRONG>) is - called and <STRONG>rmm</STRONG> is sent when <STRONG>meta</STRONG>(<EM>win</EM>, <STRONG>FALSE</STRONG>) is called. + Initially, whether the terminal returns 7- or 8-bit character codes on + input depends on the configuration of the terminal driver; on POSIX + systems, see <STRONG>termios(3)</STRONG>. To force 8 bits to be returned, call + <STRONG>meta(</STRONG>...<STRONG>,</STRONG> <STRONG>TRUE)</STRONG>; this is equivalent, on POSIX systems, to setting the + CS8 flag on the terminal. To force 7 bits to be returned, call + <STRONG>meta(</STRONG>...<STRONG>,</STRONG> <STRONG>FALSE)</STRONG>; this is equivalent, on POSIX systems, to setting the + CS7 flag on the terminal. <EM>curses</EM> ignores the window argument <EM>win</EM>. If + the <EM>terminfo</EM> string capabilities <STRONG>meta_on</STRONG> (<STRONG>smm</STRONG>) and <STRONG>meta_off</STRONG> (<STRONG>rmm</STRONG>) are + defined for the terminal type, enabling meta mode sends <STRONG>smm</STRONG>'s value to + the terminal and disabling it sends that of <STRONG>rmm</STRONG> to the terminal. </PRE><H3><a name="h3-nl_nonl">nl, nonl</a></H3><PRE> - The <STRONG>nl</STRONG> and <STRONG>nonl</STRONG> routines control whether the underlying display device - translates the return key into newline on input. + Initially, whether the terminal reports a carriage return using the + character code for a line feed in cbreak or raw modes depends on the + configuration of the terminal driver; see <STRONG>termios(3)</STRONG>. <STRONG>nl</STRONG> configures + the terminal to perform this translation. <STRONG>nonl</STRONG> disables it. Under its + canonical ("cooked") line discipline, the terminal driver always + translates carriage returns to line feeds. </PRE><H3><a name="h3-nodelay">nodelay</a></H3><PRE> - The <STRONG>nodelay</STRONG> option causes <STRONG>getch</STRONG> to be a non-blocking call. If no input - is ready, <STRONG>getch</STRONG> returns <STRONG>ERR</STRONG>. If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <STRONG>getch</STRONG> waits - until a key is pressed. + <STRONG>nodelay</STRONG> configures the input character reading function to be non- + blocking for window <EM>win</EM>. If no input is ready, the reading function + returns <STRONG>ERR</STRONG>. If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), the reading function does not + return until it has input. </PRE><H3><a name="h3-notimeout">notimeout</a></H3><PRE> - When interpreting an escape sequence, <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> sets a timer while - waiting for the next character. If <STRONG>notimeout(</STRONG><EM>win</EM>, <STRONG>TRUE</STRONG>) is called, - then <STRONG>wgetch</STRONG> does not set a timer. The purpose of the timeout is to - distinguish sequences produced by a function key from those typed by a - user. + When <STRONG>keypad</STRONG> has been called on a window and the input character reading + function reads an ESC character from it, <EM>curses</EM> sets a timer while + waiting for the next character. If the timer elapses, <EM>curses</EM> + interprets the ESC as an explicit press of the terminal's Escape key + (or equivalent). <STRONG>notimeout(</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>TRUE)</STRONG> disables this timer. The + purpose of the timeout is to distinguish sequences produced by a + function key from those typed by a user. If this timer is disabled, + <EM>curses</EM> waits forever for subsequent keystrokes until it determines the + escape sequence to be valid or invalid. + + +</PRE><H3><a name="h3-qiflush_noqiflush">qiflush, noqiflush</a></H3><PRE> + <STRONG>qiflush</STRONG> and <STRONG>noqiflush</STRONG> configure the terminal driver's treatment of its + input and output queues when it handles the interrupt, suspend, or quit + characters under the canonical ("cooked") or cbreak line disciplines on + POSIX systems; see <STRONG>termios(3)</STRONG>. The default behavior is inherited from + the terminal driver settings. Calling <STRONG>qiflush</STRONG> configures the terminal + to <EM>flush</EM> the queues (discarding their contents) when any of these + events occurs, giving the impression of faster response to user input, + but making the library's model of the screen contents incorrect. + Calling <STRONG>noqiflush</STRONG> prevents such flushing, but might frustrate impatient + users on slow connections if a <EM>curses</EM> update of the screen is in + progress when the event occurs; see <STRONG>typeahead</STRONG> below for a mitigation of + this problem. You may want to call <STRONG>noqiflush</STRONG> in a signal handler if, + after the handler exits, you want output to continue as though the + signal had not occurred. </PRE><H3><a name="h3-raw_noraw">raw, noraw</a></H3><PRE> - The <STRONG>raw</STRONG> and <STRONG>noraw</STRONG> routines place the terminal into or out of raw mode. - Raw mode is similar to <STRONG>cbreak</STRONG> mode, in that characters typed are - immediately passed through to the user program. The differences are - that in raw mode, the interrupt, quit, suspend, and flow control - characters are all passed through uninterpreted, instead of generating - a signal. The behavior of the BREAK key depends on other bits in the - terminal driver that are not set by <EM>curses</EM>. - - -</PRE><H3><a name="h3-qiflush_nqiflush">qiflush, nqiflush</a></H3><PRE> - When the <STRONG>noqiflush</STRONG> routine is used, normal flush of input and output - queues associated with the <STRONG>INTR</STRONG>, <STRONG>QUIT</STRONG> and <STRONG>SUSP</STRONG> characters will not be - done [see <STRONG>termios(3)</STRONG>]. When <STRONG>qiflush</STRONG> is called, the queues will be - flushed when these control characters are read. You may want to call - <STRONG>noqiflush</STRONG> in a signal handler if you want output to continue as though - the interrupt had not occurred, after the handler exits. + <STRONG>raw</STRONG> configures the terminal to read input in <EM>raw</EM> <EM>mode</EM>, which is similar + to cbreak mode (see <STRONG>cbreak</STRONG> above) except that it furthermore passes + through the terminal's configured interrupt, quit, suspend, and flow + control characters uninterpreted to the application, instead of + generating a signal or acting on I/O flow. The behavior of the + terminal's "Break" key (if any) depends on terminal driver + configuration parameters that <EM>curses</EM> does not handle. <STRONG>noraw</STRONG> restores + the terminal's canonical ("cooked") line discipline. </PRE><H3><a name="h3-timeout_wtimeout">timeout, wtimeout</a></H3><PRE> - The <STRONG>timeout</STRONG> and <STRONG>wtimeout</STRONG> routines set blocking or non-blocking read for - a given window. If <EM>delay</EM> is negative, a blocking read is used (i.e., - waits indefinitely for input). If <EM>delay</EM> is zero, then a non-blocking - read is used (i.e., <EM>read</EM> returns <STRONG>ERR</STRONG> if no input is waiting). If <EM>delay</EM> - is positive, then <EM>read</EM> blocks for <EM>delay</EM> milliseconds, and returns <STRONG>ERR</STRONG> - if there is still no input. Hence, these routines provide the same - functionality as <STRONG>nodelay</STRONG>, plus the additional capability of being able - to block for only <EM>delay</EM> milliseconds (where <EM>delay</EM> is positive). + <STRONG>wtimeout</STRONG> configures whether a <EM>curses</EM> input character reading function + called on window <EM>win</EM> uses blocking or non-blocking reads. If <EM>delay</EM> is + negative, <EM>curses</EM> uses a blocking read, waiting indefinitely for input. + If <EM>delay</EM> is zero, the read is non-blocking; an input character reading + function returns <STRONG>ERR</STRONG> if no input is pending. If <EM>delay</EM> is positive, an + input character reading function blocks for <EM>delay</EM> milliseconds, and + returns <STRONG>ERR</STRONG> if the delay elapses and there is still no input pending. + <STRONG>timeout</STRONG> calls <STRONG>wtimeout</STRONG> on <STRONG>stdscr</STRONG>. </PRE><H3><a name="h3-typeahead">typeahead</a></H3><PRE> - <EM>curses</EM> does "line-breakout optimization" by looking for typeahead - periodically while updating the screen. If input is found, and it is - coming from a terminal, the current update is postponed until - <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> or <STRONG>doupdate</STRONG> is called again. This allows faster response - to commands typed in advance. Normally, the input <EM>FILE</EM> pointer passed - to <STRONG>newterm</STRONG>, or <STRONG>stdin</STRONG> in the case that <STRONG>initscr</STRONG> was used, will be used to - do this typeahead checking. The <STRONG>typeahead</STRONG> routine specifies that the - file descriptor <EM>fd</EM> is to be used to check for typeahead instead. If <EM>fd</EM> - is -1, then no typeahead checking is done. + Normally, a <EM>curses</EM> library checks the terminal's input file descriptor + for activity with <STRONG>poll(2)</STRONG> or <STRONG>select(2)</STRONG> while updating the screen; if it + finds any, it postpones output until the next <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG> or + <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> call, allowing faster response to user key strokes. The + library tests the file descriptor corresponding to the <EM>FILE</EM> stream + pointer passed to <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> (or <EM>stdin</EM> if <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> was called), for + pending input. <STRONG>typeahead</STRONG> instructs <EM>curses</EM> to test file descriptor <EM>fd</EM> + instead. An <EM>fd</EM> of <STRONG>-1</STRONG> disables the check. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> - (SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful - completion, unless otherwise noted in the preceding routine - descriptions. + <STRONG>timeout</STRONG> and <STRONG>wtimeout</STRONG> return no value. + + <STRONG>cbreak</STRONG>, <STRONG>nocbreak</STRONG>, <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>keypad</STRONG>, <STRONG>meta</STRONG>, + <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>nl</STRONG>, <STRONG>nonl</STRONG>, <STRONG>raw</STRONG>, <STRONG>noraw</STRONG>, and <STRONG>typeahead</STRONG> return <STRONG>OK</STRONG> on + success and <STRONG>ERR</STRONG> on failure. - X/Open Curses does not specify any error conditions. In this - implementation, functions with a window parameter will return an error - if it is null. Any function will also return an error if the terminal - was not initialized. Also, + In <EM>ncurses</EM>, the functions in the previous paragraph return <STRONG>ERR</STRONG> if - <STRONG>halfdelay</STRONG> - returns an error if its parameter is outside the range 1..255. + <STRONG>o</STRONG> the library's <EM>TERMINAL</EM> structure for the device has not been + initialized with <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>, or <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>, or + + <STRONG>o</STRONG> <EM>win</EM> is a null pointer (except with <STRONG>intrflush</STRONG> and <STRONG>meta</STRONG>, which ignore + its value). + + Further, <STRONG>halfdelay</STRONG> returns <STRONG>ERR</STRONG> if <EM>delay</EM> is outside the range 1..255. + + See section "EXTENSIONS" below for the return values of <STRONG>is_cbreak</STRONG>, + <STRONG>is_echo</STRONG>, <STRONG>is_nl</STRONG>, and <STRONG>is_raw</STRONG>. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> <STRONG>echo</STRONG>, <STRONG>noecho</STRONG>, <STRONG>halfdelay</STRONG>, <STRONG>intrflush</STRONG>, <STRONG>meta</STRONG>, <STRONG>nl</STRONG>, <STRONG>nonl</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>, <STRONG>noqiflush</STRONG>, <STRONG>qiflush</STRONG>, <STRONG>timeout</STRONG>, and <STRONG>wtimeout</STRONG> may be implemented as macros. - <STRONG>noraw</STRONG> and <STRONG>nocbreak</STRONG> follow historical practice in that they attempt to - restore normal ("cooked") mode from raw and cbreak modes respectively. - Mixing <STRONG>raw</STRONG>/<STRONG>noraw</STRONG> and <STRONG>cbreak</STRONG>/<STRONG>nocbreak</STRONG> calls leads to terminal driver - control states that are hard to predict or understand; doing so is not - recommended. + <STRONG>noraw</STRONG> and <STRONG>nocbreak</STRONG> follow historical practice in that they attempt to + restore the terminal's canonical ("cooked") line discipline from raw + and cbreak, respectively. Mixing <STRONG>raw</STRONG>/<STRONG>noraw</STRONG> calls with <STRONG>cbreak</STRONG>/<STRONG>nocbreak</STRONG> + calls leads to terminal driver control states that are hard to predict + or understand; doing so is not recommended. + + <EM>curses</EM> documentation uses the terms "delay" and "timeout" freely to + describe two related but distinct aspects of input handling, at the + risk of confusing the user. The functions <STRONG>halfdelay</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>timeout</STRONG>, + and <STRONG>wtimeout</STRONG> configure whether the input character reading function + (<STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> or <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG>) waits for keyboard input to begin, and for + how long. <STRONG>keypad</STRONG> configures whether that function waits for further + input if the first character it reads is ESC. Calling <STRONG>notimeout</STRONG>, which + has nothing to do with <STRONG>timeout</STRONG> or <STRONG>wtimeout</STRONG>, makes this delay in + expectation of further characters effectively infinite. X/Open Curses + affords no means of otherwise configuring the length of this second + delay, but an AIX and <EM>ncurses</EM> extension, <STRONG>ESCDELAY</STRONG>, is available both as + an environment variable and a global symbol permitting the user and + application, respectively, to do so; see <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> and + <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>. </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - <EM>ncurses</EM> provides four "is_" functions that may be used to detect if the - corresponding flags were set or reset. + <EM>ncurses</EM> provides four "is_" functions corresponding to <STRONG>cbreak</STRONG>, <STRONG>echo</STRONG>, + <STRONG>nl</STRONG>, and <STRONG>raw</STRONG>, permitting their states to be queried by the application. <STRONG>Query</STRONG> <STRONG>Set</STRONG> <STRONG>Reset</STRONG> ------------------------------ @@ -270,86 +319,100 @@ In each case, the function returns - 1 if the flag is set, - - 0 if the flag is reset, or + <STRONG>1</STRONG> if the option is set, - -1 if the library is not initialized. + <STRONG>0</STRONG> if the option is unset, or - They were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and are not found in SVr4 <EM>curses</EM>, - 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> implementation. + <STRONG>-1</STRONG> if the library's <EM>TERMINAL</EM> structure for the device has not been + initialized. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> Applications employing <EM>ncurses</EM> extensions should condition their use on the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. - Except as noted in section "EXTENSIONS" above, X/Open Curses, Issue 4, - Version 2 describes these functions. - - <EM>ncurses</EM> follows X/Open Curses and the historical practice of AT&T - <EM>curses</EM> implementations, in that the echo bit is cleared when <EM>curses</EM> - initializes the terminal state. BSD <EM>curses</EM> differed from this - slightly; it left the echo bit on at initialization, but the BSD <STRONG>raw</STRONG> - call turned it off as a side effect. For best portability, set <STRONG>echo</STRONG> or - <STRONG>noecho</STRONG> explicitly just after initialization, even if your program - remains in cooked mode. - - X/Open Curses is ambiguous regarding whether <STRONG>raw</STRONG> should disable the - CR/LF translations controlled by <STRONG>nl</STRONG> and <STRONG>nonl</STRONG>. BSD <EM>curses</EM> did turn off - these translations; AT&T <EM>curses</EM> (at least as late as SVr1) did not. - <EM>ncurses</EM> does so, on the assumption that a programmer requesting raw - input wants a clean (ideally, 8-bit clean) connection that the + Except as noted in section "EXTENSIONS" above, X/Open Curses Issue 4 + describes these functions. It specifies no error conditions for them. + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". + + <EM>ncurses</EM> follows X/Open Curses and the historical practice of System V + <EM>curses</EM>, clearing the terminal driver's "echo" flag when initializing + the screen. BSD <EM>curses</EM> did not, but its <EM>raw</EM> function turned it off as + a side effect. For best portability, call <EM>echo</EM> or <EM>noecho</EM> explicitly + just after initialization, even if your program retains the terminal's + canonical ("cooked") line discipline. + + X/Open Curses is ambiguous regarding whether <EM>raw</EM> should disable the + carriage return and line feed translation feature controlled by <EM>nl</EM> and + <EM>nonl</EM>. BSD <EM>curses</EM> turned off these translations; System V <EM>curses</EM> did + not. <EM>ncurses</EM> does so, on the assumption that a programmer requesting + raw input wants a clean (ideally, 8-bit clean) connection that the operating system will not alter. - When <STRONG>keypad</STRONG> is first enabled, <EM>ncurses</EM> loads the key definitions for the - current terminal description. If the terminal description includes - extended string capabilities, e.g., from using the <STRONG>-x</STRONG> option of <STRONG>tic</STRONG>, - then <EM>ncurses</EM> also defines keys for the capabilities whose names begin - with "k". The corresponding keycodes are generated and (depending on - previous loads of terminal descriptions) may differ from one execution - of a program to the next. The generated keycodes are recognized by the - <STRONG><A HREF="curs_util.3x.html">keyname(3x)</A></STRONG> function (which will then return a name beginning with "k" - denoting the terminfo capability name rather than "K", used for <EM>curses</EM> - key names). On the other hand, an application can use <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> - to establish a specific keycode for a given string. This makes it - possible for an application to check for an extended capability's - presence with <STRONG>tigetstr</STRONG>, and reassign the keycode to match its own - needs. - - Low-level applications can use <STRONG>tigetstr</STRONG> to obtain the definition of any - particular string capability. Higher-level applications which use the - <EM>curses</EM> <STRONG>wgetch</STRONG> and similar functions to return keycodes rely upon the - order in which the strings are loaded. If more than one key definition - has the same string value, then <STRONG>wgetch</STRONG> can return only one keycode. - Most <EM>curses</EM> implementations (including <EM>ncurses</EM>) load key definitions in - the order defined by the array of string capability names. The last - key to be loaded determines the keycode which will be returned. In - <EM>ncurses</EM>, you may also have extended capabilities interpreted as key - definitions. These are loaded after the predefined keys, and if a - capability's value is the same as a previously-loaded key definition, - the later definition is the one used. + When <STRONG>keypad</STRONG> is first enabled for a window, <EM>ncurses</EM> loads the standard + function key string capabilities for the terminal type description of + its screen; see the entries beginning with "key_" in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. If + that description includes extended string capabilities, produced by the + <STRONG>-x</STRONG> option of <STRONG><A HREF="tic.1m.html">tic(1)</A></STRONG>, for example, then <EM>ncurses</EM> also defines keys for + the capabilities whose codes begin with "k". <EM>ncurses</EM> generates a + numeric key code for each such extended capability; depending on + previous loads of terminal type descriptions, these may differ from one + execution of a program to the next. <STRONG><A HREF="curs_util.3x.html">keyname(3x)</A></STRONG> recognizes the + generated key codes and returns a name beginning with "k" denoting the + <EM>terminfo</EM> capability name rather than "KEY_", used for <EM>curses</EM> key names. + On the other hand, an application can use <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> to bind a + selected key to a string of the programmer's choice. This feature + enables an application to check for its presence with <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG>, and + reassign the numeric key code to match its own needs. + + Low-level applications can use <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> to obtain the definition of + any string capability. <EM>curses</EM> applications use the input character + reading function to obtain key codes from input and rely upon the order + in which the string capabilities are loaded. Multiple key capability + strings can have the same value, but the input character reading + function can report only one key code. Most <EM>curses</EM> implementations + (including <EM>ncurses</EM>) load key definitions in the order they appear in + the <STRONG>strfnames</STRONG> array of string capability names; see <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>. + The last capability read using a particular definition determines the + key code to be reported. In <EM>ncurses</EM>, extended capabilities can be + interpreted as key definitions. The library loads these after its + built-in definitions, and if an extended capability's value is the same + as one previously loaded, the library uses the later definition. </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - Formerly, <EM>ncurses</EM> used <STRONG>nl</STRONG> and <STRONG>nonl</STRONG> to control the conversion of + 4BSD (1980) introduced <EM>echo</EM>, <EM>noecho</EM>, <EM>nl</EM>, <EM>nonl</EM>, <EM>raw</EM>, and <EM>noraw</EM>. + + SVr2 (1984) featured a new terminal driver, extending the <EM>curses</EM> API to + support it with <EM>cbreak</EM>, <EM>nocbreak</EM>, <EM>intrflush</EM>, <EM>keypad</EM>, <EM>meta</EM>, <EM>nodelay</EM>, and + <EM>typeahead</EM>. + + SVr3 (1987) added <EM>halfdelay</EM>, <EM>notimeout</EM>, and <EM>wtimeout</EM>. <EM>qiflush</EM> and + <EM>noqiflush</EM> appeared in SVr3.1 (1987), at which point <EM>intrflush</EM> became a + wrapper for either of these functions, depending on the value of its + Boolean argument. SVr3.1 also added <EM>timeout</EM>. + + <EM>ncurses</EM> 6.5 (2024) introduced <EM>is</EM><STRONG>_</STRONG><EM>cbreak</EM>, <EM>is</EM><STRONG>_</STRONG><EM>echo</EM>, <EM>is</EM><STRONG>_</STRONG><EM>nl</EM>, and <EM>is</EM><STRONG>_</STRONG><EM>raw</EM>. + + Formerly, <EM>ncurses</EM> used <EM>nl</EM> and <EM>nonl</EM> to control the conversion of newlines to carriage return/line feed on output as well as input. X/Open Curses documents the use of these functions only for input. This difference arose from converting the <EM>pcurses</EM> source (1986), which used <STRONG>ioctl(2)</STRONG> calls and the <EM>sgttyb</EM> structure, to <EM>termios</EM> (the POSIX - terminal API). In the former, both input and output were controlled - via a single option <STRONG>CRMOD</STRONG>, while the latter separates these features. - Because that conversion interferes with output optimization, <EM>ncurses</EM> - 6.2 (2020) amended <STRONG>nl</STRONG> and <STRONG>nonl</STRONG> to eliminate their effect on output. + terminal API). In the former, both input and output conversions were + controlled via a single option "CRMOD", while the latter separates + these features. Because that conversion interferes with output + optimization, <EM>ncurses</EM> 6.2 (2020) amended <EM>nl</EM> and <EM>nonl</EM> to eliminate their + effect on output. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, - <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG>termios(3)</STRONG> - - + <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG>termios(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> -ncurses 6.5 2024-04-13 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> +ncurses 6.6 2025-10-04 <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -366,8 +429,8 @@ ncurses 6.5 2024-04-13 <STRONG><A HREF=" <li><a href="#h3-nl_nonl">nl, nonl</a></li> <li><a href="#h3-nodelay">nodelay</a></li> <li><a href="#h3-notimeout">notimeout</a></li> +<li><a href="#h3-qiflush_noqiflush">qiflush, noqiflush</a></li> <li><a href="#h3-raw_noraw">raw, noraw</a></li> -<li><a href="#h3-qiflush_nqiflush">qiflush, nqiflush</a></li> <li><a href="#h3-timeout_wtimeout">timeout, wtimeout</a></li> <li><a href="#h3-typeahead">typeahead</a></li> </ul> diff --git a/doc/html/man/curs_ins_wch.3x.html b/doc/html/man/curs_ins_wch.3x.html index 7c25b2ed7e9d..9f087cec8ab6 100644 --- a/doc/html/man/curs_ins_wch.3x.html +++ b/doc/html/man/curs_ins_wch.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 2002-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,73 +27,79 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_ins_wch.3x,v 1.30 2024/04/20 19:18:18 tom Exp @ + * @Id: curs_ins_wch.3x,v 1.52 2025/10/21 00:09:49 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_ins_wch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_ins_wch 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_ins_wch 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_ins_wch 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>ins_wch</STRONG>, <STRONG>mvins_wch</STRONG>, <STRONG>mvwins_wch</STRONG>, <STRONG>wins_wch</STRONG> - insert a <EM>curses</EM> complex + <STRONG>ins_wch</STRONG>, <STRONG>wins_wch</STRONG>, <STRONG>mvins_wch</STRONG>, <STRONG>mvwins_wch</STRONG> - insert a <EM>curses</EM> complex character in a window </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>ins_wch(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wins_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvins_wch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwins_wch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>ins_wch(const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wins_wch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvins_wch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwins_wch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These functions insert the <EM>curses</EM> complex character <EM>wch</EM> at the cursor - in the specified window <EM>win</EM> (or <STRONG>stdscr</STRONG>). The character previously at - the cursor and any to its right move one cell to the right; the - rightmost character on the line is discarded. The cursor does not - advance. + <STRONG>wins_wch</STRONG> inserts the <EM>curses</EM> complex character <EM>wch</EM> at the cursor + position in the window <EM>win</EM>. The character previously at the cursor and + any to its right move one cell to the right; the formerly rightmost + character on the line is discarded. Unlike <STRONG><A HREF="curs_add_wch.3x.html">add_wch(3x)</A></STRONG>, <STRONG>wins_wch</STRONG> does + not advance the cursor. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this + function. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - Functions taking a <EM>WINDOW</EM> pointer argument fail if the pointer is <STRONG>NULL</STRONG>. + In <EM>ncurses</EM>, they return <STRONG>ERR</STRONG> if + + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, or - Functions prefixed with "mv" first perform cursor movement and fail if + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer. + + Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - A terminal's <STRONG>insert_character</STRONG> (<STRONG>ich1</STRONG>) capability is not necessarily - employed. - <STRONG>ins_wch</STRONG>, <STRONG>mvins_wch</STRONG>, and <STRONG>mvwins_wch</STRONG> may be implemented as macros. + <EM>curses</EM> does not necessarily employ the terminal's <STRONG>insert_character</STRONG> + (<STRONG>ich1</STRONG>) capability to achieve insertion. -</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. - SVr4 describes successful return values only as "an integer value other - than <STRONG>ERR</STRONG>". +</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - SVr4 (1989) implemented these functions under the names <STRONG>inswch</STRONG>, - <STRONG>winswch</STRONG>, <STRONG>mvinswch</STRONG>, and <STRONG>mvwinswch</STRONG>. + X/Open Curses Issue 4 (1995) initially specified these functions. The + System V Interface Definition Version 4 of the same year specified a + function named <EM>winswch</EM> (and the usual variants). This was a later + addition to SVr4.<EM>x</EM>, not appearing in the first SVr4 (1989). It + differed from X/Open's later <EM>wins</EM><STRONG>_</STRONG><EM>wch</EM> in that it took an argument of + type <EM>chtype</EM> instead of <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> @@ -102,9 +108,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_ins_wstr.3x.html b/doc/html/man/curs_ins_wstr.3x.html index f2982eaa14ab..c6f9e46a71a0 100644 --- a/doc/html/man/curs_ins_wstr.3x.html +++ b/doc/html/man/curs_ins_wstr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 2002-2012,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,104 +27,117 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_ins_wstr.3x,v 1.38 2024/04/20 21:23:08 tom Exp @ + * @Id: curs_ins_wstr.3x,v 1.60 2025/03/01 21:30:14 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_ins_wstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_ins_wstr 3x 2025-03-01 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_ins_wstr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_ins_wstr 3x 2025-03-01 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>ins_wstr</STRONG>, <STRONG>ins_nwstr</STRONG>, <STRONG>wins_wstr</STRONG>, <STRONG>wins_nwstr</STRONG>, <STRONG>mvins_wstr</STRONG>, <STRONG>mvins_nwstr</STRONG>, - <STRONG>mvwins_wstr</STRONG>, <STRONG>mvwins_nwstr</STRONG> - insert a wide-character string in a <EM>curses</EM> + <STRONG>ins_wstr</STRONG>, <STRONG>wins_wstr</STRONG>, <STRONG>mvins_wstr</STRONG>, <STRONG>mvwins_wstr</STRONG>, <STRONG>ins_nwstr</STRONG>, <STRONG>wins_nwstr</STRONG>, + <STRONG>mvins_nwstr</STRONG>, <STRONG>mvwins_nwstr</STRONG> - insert a wide-character string in a <EM>curses</EM> window </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>ins_wstr(const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>ins_nwstr(const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wins_wstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wins_nwstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>ins_wstr(const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wins_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvins_wstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwins_wstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvins_wstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvins_nwstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwins_wstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwins_nwstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>ins_nwstr(const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wins_nwstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvins_nwstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwins_nwstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> + <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These routines insert a <STRONG>wchar_t</STRONG> character string (as many characters as - will fit on the line) before the character under the cursor, as if - calling <STRONG><A HREF="curs_ins_wch.3x.html">wins_wch(3x)</A></STRONG>. All characters to the right of the cursor are - shifted right, with the possibility of the rightmost characters on the - line being lost. No wrapping is performed. - - The cursor position does not change (after moving to <EM>y</EM>, <EM>x</EM>, if - specified). - - The functions with <EM>n</EM> as the last argument insert a leading substring of - at most <EM>n</EM> <STRONG>wchar_t</STRONG> characters. If <EM>n</EM> is less than zero, the entire - string is inserted (stopping on a L'\0' character). - - Special characters are handled as in <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG>. + <STRONG>wins_wstr</STRONG> inserts a wide-character string <EM>wstr</EM> before the character at + the cursor in window <EM>win</EM> as if by calling <STRONG><A HREF="curs_ins_wch.3x.html">wins_wch(3x)</A></STRONG> for each <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> + in <EM>wstr</EM>. No line wrapping is performed. Characters to the right of + the cursor are shifted right; those at the right edge of the window may + be lost. <STRONG>wins_wstr</STRONG> stops inserting if it would have to wrap to the + next line to write the next <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> in <EM>wstr</EM>. The cursor position does + not change (after moving to (<EM>y</EM>, <EM>x</EM>), if specified). <STRONG>wins_nwstr</STRONG> does the + same, but inserts at most <EM>n</EM> wide characters, or as many as possible (up + to the end of the line) if <EM>n</EM> is negative. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the + variants of these functions. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All functions return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. + + In <EM>ncurses</EM>, they return <STRONG>ERR</STRONG> if - X/Open Curses does not specify any error conditions. This - implementation returns an error + <STRONG>o</STRONG> <EM>win</EM> is <EM>NULL</EM>, - <STRONG>o</STRONG> if the <EM>win</EM> parameter is null or + <STRONG>o</STRONG> <EM>wstr</EM> is <EM>NULL</EM>, - <STRONG>o</STRONG> if the <EM>wstr</EM> parameter is null or + <STRONG>o</STRONG> the first wide character in <EM>wstr</EM> is a non-spacing character, or - <STRONG>o</STRONG> if the <STRONG>wins_wch</STRONG> function returns an error. + <STRONG>o</STRONG> an internal <STRONG><A HREF="curs_ins_wch.3x.html">wins_wch(3x)</A></STRONG> call returns <STRONG>ERR</STRONG>. - Functions prefixed with "mv" first perform cursor movement and fail if + Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All but <STRONG>wins_nwstr</STRONG> may be macros. + All of these functions except <STRONG>wins_nwstr</STRONG> may be implemented as macros. + - If the first character in the string is a non-spacing character, these - functions will fail. X/Open Curses does not define what will happen if - a non-spacing character follows a control character. +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>ins_nwstr</STRONG>, <STRONG>wins_nwstr</STRONG>, <STRONG>mvins_nwstr</STRONG>, and <STRONG>mvwins_nwstr</STRONG>'s acceptance of + negative <EM>n</EM> values is an <EM>ncurses</EM> extension. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4, which adds - <EM>const</EM> qualifiers to the arguments. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. - X/Open states that the entire string is inserted if <EM>n</EM> is less than 1. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + + X/Open Curses does not specify what happens if a non-spacing character + follows a control character. + + Issue 4 states that the entire string is inserted if <EM>n</EM> is less than 1. This is probably an error, because it is inconsistent with other - functions, and differs from the X/Open implementation on Solaris. + functions such as <EM>waddwstr</EM>, and differs from the SVr4 <EM>curses</EM> and + Solaris <EM>xcurses</EM> implementations. Nevertheless, Issue 7 retains the + language. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + X/Open Curses Issue 4 (1995) initially specified these functions. The + System V Interface Definition Version 4 (1995), specified functions + named <EM>winswstr</EM> and <EM>winsnwstr</EM> (and the usual variants). These were + later additions to SVr4.<EM>x</EM>, not appearing in the first SVr4 (1989). + They differ from X/Open's later <EM>wins</EM><STRONG>_</STRONG><EM>wstr</EM> and <EM>wins</EM><STRONG>_</STRONG><EM>nwstr</EM> in that their + <EM>wstr</EM> parameters are not <EM>const</EM>-qualified. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="curs_insstr.3x.html">curs_insstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library + <STRONG><A HREF="curs_insstr.3x.html">curs_insstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in its non-wide-character configuration. <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG> +ncurses 6.6 2025-03-01 <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -133,7 +146,9 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="cu <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_insch.3x.html b/doc/html/man/curs_insch.3x.html index 5f60c67c0fde..6c732a57cf4e 100644 --- a/doc/html/man/curs_insch.3x.html +++ b/doc/html/man/curs_insch.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_insch.3x,v 1.40 2024/04/20 19:03:47 tom Exp @ + * @Id: curs_insch.3x,v 1.56 2025/03/08 23:10:02 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_insch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_insch 3x 2025-03-08 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_insch 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_insch 3x 2025-03-08 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>insch</STRONG>, <STRONG>winsch</STRONG>, <STRONG>mvinsch</STRONG>, <STRONG>mvwinsch</STRONG> - insert a <EM>curses</EM> character in a window @@ -55,22 +53,28 @@ <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> <STRONG>int</STRONG> <STRONG>insch(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>winsch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>winsch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>mvinsch(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwinsch(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwinsch(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These functions insert the <EM>curses</EM> character <EM>ch</EM> at the cursor in the - specified window <EM>win</EM> (or <STRONG>stdscr</STRONG>). The character previously at the - cursor and any to its right move one cell to the right; the rightmost - character on the line is discarded. The cursor does not advance. + <STRONG>winsch</STRONG> inserts the <EM>curses</EM> character <EM>ch</EM> at the cursor position in the + window <EM>win</EM>. The character previously at the cursor and any to its + right move one cell to the right; the formerly rightmost character on + the line is discarded. Unlike <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>, <STRONG>winsch</STRONG> does not advance the + cursor. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of this function. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - Functions taking a <EM>WINDOW</EM> pointer argument fail if the pointer is <STRONG>NULL</STRONG>. + In <EM>ncurses</EM>, they return <STRONG>ERR</STRONG> if + + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, or + + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer. Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. @@ -79,15 +83,20 @@ </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> <STRONG>insch</STRONG>, <STRONG>mvinsch</STRONG>, and <STRONG>mvwinsch</STRONG> may be implemented as macros. - A terminal's <STRONG>insert_character</STRONG> (<STRONG>ich1</STRONG>) capability is not necessarily - employed. + <EM>curses</EM> does not necessarily employ the terminal's <STRONG>insert_character</STRONG> + (<STRONG>ich1</STRONG>) capability to achieve insertion. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - SVr4 <EM>curses</EM> describes a successful return value only as "an integer - value other than <STRONG>ERR</STRONG>". + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr2 (1984) introduced these functions. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> @@ -96,9 +105,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG> +ncurses 6.6 2025-03-08 <STRONG><A HREF="curs_insch.3x.html">curs_insch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -108,6 +115,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF= <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_insstr.3x.html b/doc/html/man/curs_insstr.3x.html index 04e0239925e2..8f3eb192fb5b 100644 --- a/doc/html/man/curs_insstr.3x.html +++ b/doc/html/man/curs_insstr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,101 +27,112 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_insstr.3x,v 1.51 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_insstr.3x,v 1.72 2025/10/21 00:11:17 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_insstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_insstr 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_insstr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_insstr 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_insstr.3x.html">curs_insstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_insstr.3x.html">curs_insstr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>insstr</STRONG>, <STRONG>insnstr</STRONG>, <STRONG>winsstr</STRONG>, <STRONG>winsnstr</STRONG>, <STRONG>mvinsstr</STRONG>, <STRONG>mvinsnstr</STRONG>, <STRONG>mvwinsstr</STRONG>, + <STRONG>insstr</STRONG>, <STRONG>winsstr</STRONG>, <STRONG>mvinsstr</STRONG>, <STRONG>mvinsnstr</STRONG>, <STRONG>insnstr</STRONG>, <STRONG>winsnstr</STRONG>, <STRONG>mvwinsstr</STRONG>, <STRONG>mvwinsnstr</STRONG> - insert a string in a <EM>curses</EM> window </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>insstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>insnstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>winsstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>winsnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>mvinsstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvinsnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwinsstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwinsnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - -</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These routines insert a character string (as many characters as will - fit on the line) before the character under the cursor, as if calling - <STRONG><A HREF="curs_insch.3x.html">winsch(3x)</A></STRONG>. All characters to the right of the cursor are shifted - right, with the possibility of the rightmost characters on the line - being lost. No wrapping is performed. + <STRONG>int</STRONG> <STRONG>insstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>winsstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvinsstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwinsstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> - The cursor position does not change (after moving to <EM>y</EM>, <EM>x</EM>, if - specified). + <STRONG>int</STRONG> <STRONG>insnstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>winsnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvinsnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwinsnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - The functions with <EM>n</EM> as the last argument insert a leading substring of - at most <EM>n</EM> characters. If <EM>n</EM> is less than zero, the entire string is - inserted (stopping on a NUL character). - Special characters are handled as in <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG>. +</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> + <STRONG>winsstr</STRONG> inserts a string <EM>str</EM> before the character at the cursor in + window <EM>win</EM> as if by calling <STRONG><A HREF="curs_insch.3x.html">winsch(3x)</A></STRONG> for each <EM>char</EM> in <EM>str</EM>. No line + wrapping is performed. Characters to the right of the cursor are + shifted right; those at the right edge of the window may be lost. + <STRONG>winsstr</STRONG> stops inserting if it would have to wrap to the next line to + write the next <EM>char</EM> in <EM>str</EM>. The cursor position does not change (after + moving to (<EM>y</EM>, <EM>x</EM>), if specified). <STRONG>insnstr</STRONG> does the same, but inserts at + most <EM>n</EM> characters, or as many as possible (up to the end of the line) + if <EM>n</EM> is negative. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these + functions. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All functions return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - X/Open Curses does not specify any error conditions. This - implementation returns an error + In <EM>ncurses</EM>, they return <STRONG>ERR</STRONG> if - <STRONG>o</STRONG> if the <EM>win</EM> parameter is null or + <STRONG>o</STRONG> <EM>win</EM> is <EM>NULL</EM>, - <STRONG>o</STRONG> if the <EM>str</EM> parameter is null or + <STRONG>o</STRONG> <EM>str</EM> is <EM>NULL</EM>, or - <STRONG>o</STRONG> the <STRONG><A HREF="curs_insch.3x.html">winsch(3x)</A></STRONG> function returns an error. + <STRONG>o</STRONG> an internal <STRONG><A HREF="curs_insch.3x.html">winsch(3x)</A></STRONG> call returns <STRONG>ERR</STRONG>. - Functions prefixed with "mv" first perform cursor movement and fail if + Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All but <STRONG>winsnstr</STRONG> may be macros. + All of these functions except <STRONG>winsnstr</STRONG> may be implemented as macros. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>insnstr</STRONG>, <STRONG>winsnstr</STRONG>, <STRONG>mvinsnstr</STRONG>, and <STRONG>mvwinsnstr</STRONG>'s acceptance of negative <EM>n</EM> + values is an <EM>ncurses</EM> extension. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4, which adds - <EM>const</EM> qualifiers to the arguments. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. - The Single Unix Specification, Version 2 states that <STRONG>insnstr</STRONG> and - <STRONG>winsnstr</STRONG> perform wrapping. This is probably an error, since it makes - this group of functions inconsistent. Also, no implementation of - curses documents this inconsistency. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - X/Open states that the entire string is inserted if <EM>n</EM> is less than 1. - This is probably an error, because it is inconsistent with other - functions, and differs from the SVr4 and X/Open implementations on - Solaris. + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". + Issue 4 distinguished <EM>insnstr</EM> and <EM>winsnstr</EM> from the other functions + documented above by stating they "do not perform wrapping". This was + probably an error, since it makes this group of functions inconsistent. + No implementation of <EM>curses</EM> manifests this inconsistency, and Issue 7 + removed the claim. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>, <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> + Issue 4 states that the entire string is inserted if <EM>n</EM> is less than 1. + This is probably an error, because it is inconsistent with other + functions such as <EM>waddstr</EM>, and differs from the SVr4 <EM>curses</EM> and Solaris + <EM>xcurses</EM> implementations. Nevertheless, Issue 7 retains the language. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr3.1 (1987) introduced <EM>winsstr</EM> and <EM>winsnstr</EM> and their variants. +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library + in its wide-character configuration (<EM>ncursesw</EM>). + + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG>, <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_insstr.3x.html">curs_insstr(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_insstr.3x.html">curs_insstr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -130,7 +141,9 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF=" <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_instr.3x.html b/doc/html/man/curs_instr.3x.html index 50d0f20e2d9b..75e03f53f558 100644 --- a/doc/html/man/curs_instr.3x.html +++ b/doc/html/man/curs_instr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,96 +27,120 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_instr.3x,v 1.51 2024/04/20 21:24:19 tom Exp @ + * @Id: curs_instr.3x,v 1.82 2025/10/21 00:04:35 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_instr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_instr 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_instr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_instr 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>instr</STRONG>, <STRONG>innstr</STRONG>, <STRONG>winstr</STRONG>, <STRONG>winnstr</STRONG>, <STRONG>mvinstr</STRONG>, <STRONG>mvinnstr</STRONG>, <STRONG>mvwinstr</STRONG>, <STRONG>mvwinnstr</STRONG> + <STRONG>instr</STRONG>, <STRONG>winstr</STRONG>, <STRONG>mvinstr</STRONG>, <STRONG>mvwinstr</STRONG>, <STRONG>innstr</STRONG>, <STRONG>winnstr</STRONG>, <STRONG>mvinnstr</STRONG>, <STRONG>mvwinnstr</STRONG> - get a string from a <EM>curses</EM> window </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>instr(char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>innstr(char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>winstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>winnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>instr(char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>winstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvinstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwinstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvinstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvinnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwinstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwinnstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>innstr(char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>winnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvinnstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwinnstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These routines return a string of characters in <EM>str</EM>, starting at the - current cursor position in the named window. Attributes are stripped - from the characters. - - The four functions with <EM>n</EM> as the last argument return a leading - substring at most <EM>n</EM> characters long (exclusive of the trailing NUL). - Transfer stops at the end of the current line, or when <EM>n</EM> characters - have been stored at the location referenced by <EM>str</EM>. + <STRONG>winstr</STRONG> extracts a string from a <EM>curses</EM> window <EM>win</EM>, starting at the + cursor and stopping at the end of the line, and stores it in <EM>str</EM>, + terminating it with a null character and omitting any attributes and + color pair identifier that <EM>curses</EM> associates with each character. + <STRONG>winnstr</STRONG> does the same, but copies at most <EM>n</EM> characters from <EM>win</EM>. A + negative <EM>n</EM> implies no limit; <STRONG>winnstr</STRONG> then works like <STRONG>winstr</STRONG>. + <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these functions. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All of the functions return <STRONG>ERR</STRONG> upon failure, or the number of - characters actually read into the string. + These functions return the count of characters copied from <EM>win</EM> to <EM>str</EM> + (not including the null terminator), or <STRONG>ERR</STRONG> upon failure. + + In <EM>ncurses</EM>, these functions fail if - X/Open Curses defines no error conditions. This implementation returns - an error + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> if the <EM>win</EM> parameter is null or + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, or - <STRONG>o</STRONG> if the <EM>chstr</EM> parameter is null. + <STRONG>o</STRONG> <EM>str</EM> is a null pointer. - Functions prefixed with "mv" first perform cursor movement and fail if + Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All routines except <STRONG>winnstr</STRONG> may be macros. + All of these functions except <STRONG>winnstr</STRONG> may be implemented as macros. - Reading a line that overflows the array pointed to by <EM>str</EM> with <STRONG>instr</STRONG>, - <STRONG>mvinstr</STRONG>, <STRONG>mvwinstr</STRONG> or <STRONG>winstr</STRONG> causes undefined results. Therefore, the - use of <STRONG>innstr</STRONG>, <STRONG>mvinnstr</STRONG>, <STRONG>mvwinnstr</STRONG>, or <STRONG>winnstr</STRONG> is recommended. + Reading a line that overflows the array pointed to by <EM>str</EM> with and its + variants causes undefined results. Instead, use the <EM>n</EM>-infixed + functions with a positive <EM>n</EM> argument no larger than the size of the + buffer backing <EM>str</EM>. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>innstr</STRONG>, <STRONG>winnstr</STRONG>, <STRONG>mvinnstr</STRONG>, and <STRONG>mvwinnstr</STRONG>'s acceptance of negative <EM>n</EM> + values is an <EM>ncurses</EM> extension. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - SVr4 does not document whether a length limit includes or excludes the - trailing NUL. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + + X/Open Curses Issues 4 and 7 both state that <EM>instr</EM>, <EM>winstr</EM>, <EM>mvinstr</EM>, + and <EM>mvwinstr</EM> return <EM>OK</EM> rather than a character count. This is likely + an erratum. - The <EM>ncurses</EM> library extends the X/Open Curses description by allowing a - negative value for <EM>n</EM>. In this case, the functions return the string - ending at the right margin. + <STRONG>o</STRONG> SVr3.1 and SVr4 implemented <EM>winstr</EM> as a wrapper around <EM>winnstr</EM>, + returning the latter's return value. X/Open Curses's specification + thus may have been an editorial solecism copied from System V's + documentation (see below) by X/Open, rather than an intentional + change. + + <STRONG>o</STRONG> <EM>ncurses</EM> retains compatibility with System V <EM>curses</EM> behavior. + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". + + SVr4 does not document whether <EM>n</EM> counts the null terminator that these + functions write to <EM>str</EM>. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr3.1 (1987) introduced these functions. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library + <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in its wide-character configuration (<EM>ncursesw</EM>). <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -125,7 +149,9 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF= <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_inwstr.3x.html b/doc/html/man/curs_inwstr.3x.html index 6c79b595fbeb..7ea4b809c64b 100644 --- a/doc/html/man/curs_inwstr.3x.html +++ b/doc/html/man/curs_inwstr.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2002-2012,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,100 +27,126 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_inwstr.3x,v 1.41 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_inwstr.3x,v 1.66 2025/10/21 00:04:48 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_inwstr 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_inwstr 3x 2025-10-20 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_inwstr 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_inwstr 3x 2025-10-20 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>inwstr</STRONG>, <STRONG>innwstr</STRONG>, <STRONG>winwstr</STRONG>, <STRONG>winnwstr</STRONG>, <STRONG>mvinwstr</STRONG>, <STRONG>mvinnwstr</STRONG>, <STRONG>mvwinwstr</STRONG>, + <STRONG>inwstr</STRONG>, <STRONG>winwstr</STRONG>, <STRONG>mvinwstr</STRONG>, <STRONG>mvwinwstr</STRONG>, <STRONG>innwstr</STRONG>, <STRONG>winnwstr</STRONG>, <STRONG>mvinnwstr</STRONG>, <STRONG>mvwinnwstr</STRONG> - get a wide-character string from a <EM>curses</EM> window </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>inwstr(wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>innwstr(wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>winwstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>winnwstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>inwstr(wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>winwstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvinwstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwinwstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvinwstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvinnwstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwinwstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwinnwstr(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>innwstr(wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>winnwstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvinnwstr(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwinnwstr(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <EM>wstr</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These routines return a string of <STRONG>wchar_t</STRONG> wide characters in <EM>wstr</EM>, - starting at the current cursor position in the named window. - - The four functions with <EM>n</EM> as the last argument return a leading - substring at most <EM>n</EM> characters long (exclusive of the trailing NUL). - Transfer stops at the end of the current line, or when <EM>n</EM> characters - have been stored at the location referenced by <EM>wstr</EM>. - - If the size <EM>n</EM> is not large enough to store a complete complex - character, an error is generated. + <STRONG>winwstr</STRONG> extracts a wide-character string from a <EM>curses</EM> window <EM>win</EM>, + starting at the cursor and stopping at the end of the line, and stores + it in <EM>wstr</EM>, terminating it with a wide null character and omitting any + attributes and color pair identifier that <EM>curses</EM> associates with each + character. <STRONG>winnwstr</STRONG> does the same, but copies at most <EM>n</EM> wide + characters from <EM>win</EM>. A negative <EM>n</EM> implies no limit; <STRONG>winnwstr</STRONG> then + works like <STRONG>winwstr</STRONG>. <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the variants of these + functions. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All routines return <STRONG>ERR</STRONG> upon failure. Upon successful completion, the - *<STRONG>inwstr</STRONG> routines return <STRONG>OK</STRONG>, and the *<STRONG>innwstr</STRONG> routines return the number - of characters read into the string. + On successful operation, these functions return the count of wide + characters copied from <EM>win</EM> to <EM>wstr</EM> (not including the wide null + terminator), or <STRONG>ERR</STRONG> upon failure. <STRONG>innwstr</STRONG>, <STRONG>winnwstr</STRONG>, <STRONG>mvinnwstr</STRONG>, and + <STRONG>mvwinnwstr</STRONG> return <STRONG>ERR</STRONG> if <EM>n</EM> is insufficiently large to store a complete + wide character string. (Recall that a <EM>curses</EM> complex character can + contain multiple wide characters, some of which may be non-spacing.) - X/Open defines no error conditions. This implementation returns an - error + In <EM>ncurses</EM>, these functions return <STRONG>ERR</STRONG> if - <STRONG>o</STRONG> if the <EM>win</EM> parameter is null or + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> if the <EM>wstr</EM> parameter is null, or + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, or - <STRONG>o</STRONG> if no characters could be read. + <STRONG>o</STRONG> <EM>wstr</EM> is a null pointer. - Functions prefixed with "mv" first perform cursor movement and fail if + Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All routines except <STRONG>winnwstr</STRONG> may be macros. + All of these functions except <STRONG>winnwstr</STRONG> may be implemented as macros. + + Reading a line that overflows the array pointed to by <EM>wstr</EM> and its + variants causes undefined results. Instead, use the <EM>n</EM>-infixed + functions with a positive <EM>n</EM> argument no larger than the size of the + buffer backing <EM>wstr</EM>. - Each cell in the window holds a complex character (a spacing character - and zero or more non-spacing characters) together with attributes and - color. These functions store only the wide characters, ignoring - attributes and color. Use <STRONG>in_wchstr</STRONG> to return the complex characters - from a window. - Reading a line that overflows the array pointed to by <EM>wstr</EM> with <STRONG>inwstr</STRONG>, - <STRONG>mvinwstr</STRONG>, <STRONG>mvwinwstr</STRONG> or <STRONG>winwstr</STRONG> causes undefined results. Therefore, - the use of <STRONG>innwstr</STRONG>, <STRONG>mvinnwstr</STRONG>, <STRONG>mvwinnwstr</STRONG>, or <STRONG>winnwstr</STRONG> is recommended. +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>innwstr</STRONG>, <STRONG>winnwstr</STRONG>, <STRONG>mvinnwstr</STRONG>, and <STRONG>mvwinnwstr</STRONG>'s acceptance of negative <EM>n</EM> + values is an <EM>ncurses</EM> extension. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inch.3x.html">curs_inch(3x)</A></STRONG>, <STRONG><A HREF="curs_inchstr.3x.html">curs_inchstr(3x)</A></STRONG>, <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG>, - <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG> + Notwithstanding the foregoing, X/Open Curses Issues 4 and 7 both state + that <EM>innwstr</EM>, <EM>winnwstr</EM>, <EM>mvinnwstr</EM>, and <EM>mvwinnwstr</EM> "fail ... [i]f the + array is not large enough to contain any complete characters". + Strictly interpreted, this means that a caller of these functions + cannot use their return values to detect truncation of a wide-character + string copied from more than one character cell in <EM>win</EM>. <EM>ncurses</EM> + reports any truncation with <EM>ERR</EM>. + X/Open Curses specifies <EM>inwstr</EM>, <EM>winwstr</EM>, <EM>mvinwstr</EM>, and <EM>mvwinwstr</EM> as + returning <EM>OK</EM> rather than a (wide) character count, unlike their non- + wide counterparts <EM>instr</EM>, <EM>winstr</EM>, <EM>mvinstr</EM>, and <EM>mvwinstr</EM>. <EM>ncurses</EM> + regards this inconsistency as an error in the standard. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + The System V Interface Definition, Version 4 (1995), specified <EM>winwstr</EM> + and <EM>winnwstr</EM> (and the usual variants). These were later additions to + SVr4.<EM>x</EM>, not appearing in the first SVr4 (1989). Their synopses + described each function as taking an argument of type pointer-to-<EM>char</EM> + instead of pointer-to-<EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>, despite describing them as "returning + the string of <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> in <EM>str</EM>". Presumably this was an error in the + System V Interface Definition. + + +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG> describes comparable functions of the <EM>ncurses</EM> library in + its non-wide-character configuration. + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_in_wch.3x.html">curs_in_wch(3x)</A></STRONG>, <STRONG><A HREF="curs_in_wchstr.3x.html">curs_in_wchstr(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> +ncurses 6.6 2025-10-20 <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -129,7 +155,9 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF=" <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_kernel.3x.html b/doc/html/man/curs_kernel.3x.html index 90042caf9d2e..c296f96b215a 100644 --- a/doc/html/man/curs_kernel.3x.html +++ b/doc/html/man/curs_kernel.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,29 +27,27 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_kernel.3x,v 1.61 2024/04/20 21:24:19 tom Exp @ + * @Id: curs_kernel.3x,v 1.89 2025/08/16 19:50:07 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_kernel 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_kernel 3x 2025-08-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_kernel 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_kernel 3x 2025-08-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>def_prog_mode</STRONG>, <STRONG>def_shell_mode</STRONG>, <STRONG>reset_prog_mode</STRONG>, <STRONG>reset_shell_mode</STRONG>, - <STRONG>resetty</STRONG>, <STRONG>savetty</STRONG>, <STRONG>getsyx</STRONG>, <STRONG>setsyx</STRONG>, <STRONG>ripoffline</STRONG>, <STRONG>curs_set</STRONG>, <STRONG>napms</STRONG> - low- - level <EM>curses</EM> routines + <STRONG>resetty</STRONG>, <STRONG>savetty</STRONG>, <STRONG>getsyx</STRONG>, <STRONG>setsyx</STRONG>, <STRONG>curs_set</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>napms</STRONG>, <STRONG>ripoffline</STRONG> - + low-level <EM>curses</EM> routines </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> @@ -67,9 +65,10 @@ <STRONG>void</STRONG> <STRONG>getsyx(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> <STRONG>void</STRONG> <STRONG>setsyx(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>ripoffline(int</STRONG> <EM>line</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>init</EM><STRONG>)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>int));</STRONG> <STRONG>int</STRONG> <STRONG>curs_set(int</STRONG> <EM>visibility</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvcur(int</STRONG> <EM>oldrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldcol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newcol</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>napms(int</STRONG> <EM>ms</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>ripoffline(int</STRONG> <EM>line</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>init</EM><STRONG>)(WINDOW</STRONG> <STRONG>*,</STRONG> <STRONG>int));</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> @@ -82,133 +81,201 @@ The <STRONG>def_prog_mode</STRONG> and <STRONG>def_shell_mode</STRONG> routines save the current terminal modes as the "program" (in <STRONG>curses</STRONG>) or "shell" (not in <STRONG>curses</STRONG>) state for use by the <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG> routines. This is done - automatically by <STRONG>initscr</STRONG>. There is one such save area for each screen + automatically by <STRONG>initscr</STRONG>. There is one such save area for each screen context allocated by <STRONG>newterm</STRONG>. </PRE><H3><a name="h3-reset_prog_mode_reset_shell_mode">reset_prog_mode, reset_shell_mode</a></H3><PRE> - The <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG> routines restore the terminal - to "program" (in <STRONG>curses</STRONG>) or "shell" (out of <STRONG>curses</STRONG>) state. These are - done automatically by <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> and, after an <STRONG>endwin</STRONG>, by <STRONG>doupdate</STRONG>, so + The <STRONG>reset_prog_mode</STRONG> and <STRONG>reset_shell_mode</STRONG> routines restore the terminal + to "program" (in <STRONG>curses</STRONG>) or "shell" (out of <STRONG>curses</STRONG>) state. These are + done automatically by <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> and, after an <STRONG>endwin</STRONG>, by <STRONG>doupdate</STRONG>, so they normally are not called. </PRE><H3><a name="h3-resetty_savetty">resetty, savetty</a></H3><PRE> - The <STRONG>resetty</STRONG> and <STRONG>savetty</STRONG> routines save and restore the state of the - terminal modes. <STRONG>savetty</STRONG> saves the current state in a buffer and + The <STRONG>resetty</STRONG> and <STRONG>savetty</STRONG> routines save and restore the state of the + terminal modes. <STRONG>savetty</STRONG> saves the current state in a buffer and <STRONG>resetty</STRONG> restores the state to what it was at the last call to <STRONG>savetty</STRONG>. </PRE><H3><a name="h3-getsyx">getsyx</a></H3><PRE> - The <STRONG>getsyx</STRONG> routine returns the current coordinates of the <EM>virtual</EM> - <EM>screen</EM> cursor in <EM>y</EM> and <EM>x</EM>. If <STRONG>leaveok</STRONG> is currently <STRONG>TRUE</STRONG>, then <STRONG>-1</STRONG>,<STRONG>-1</STRONG> is - returned. If lines have been removed from the top of the screen, using - <STRONG>ripoffline</STRONG>, <EM>y</EM> and <EM>x</EM> include these lines; therefore, <EM>y</EM> and <EM>x</EM> should be - used only as arguments for <STRONG>setsyx</STRONG>. + <STRONG>getsyx</STRONG> stores the coordinates of virtual screen (<STRONG>newscr</STRONG>) cursor in <EM>y</EM> + and <EM>x</EM>. If <STRONG>newscr</STRONG>'s <STRONG><A HREF="leaveok.3x.html">leaveok(3x)</A></STRONG> output option is <STRONG>TRUE</STRONG>, <STRONG>getsyx</STRONG> stores <STRONG>-1</STRONG> + in both <EM>y</EM> and <EM>x</EM>. If lines have been removed from the top of the screen + using <STRONG>ripoffline</STRONG>, <EM>y</EM> includes these lines; therefore, <EM>y</EM> and <EM>x</EM> populated + by <STRONG>getsyx</STRONG> should be used only as arguments for <STRONG>setsyx</STRONG>. - Few applications will use this feature, most use <STRONG>getyx</STRONG> instead. + Few applications use this feature; most call <STRONG><A HREF="curs_getyx.3x.html">getyx(3x)</A></STRONG> instead. </PRE><H3><a name="h3-setsyx">setsyx</a></H3><PRE> - The <STRONG>setsyx</STRONG> routine sets the <EM>virtual</EM> <EM>screen</EM> cursor to <EM>y</EM>, <EM>x</EM>. If <EM>y</EM> and <EM>x</EM> - are both <STRONG>-1</STRONG>, then <STRONG>leaveok</STRONG> is set. The two routines <STRONG>getsyx</STRONG> and <STRONG>setsyx</STRONG> - are designed to be used by a library routine, which manipulates <STRONG>curses</STRONG> - windows but does not want to change the current position of the - program's cursor. The library routine would call <STRONG>getsyx</STRONG> at the - beginning, do its manipulation of its own windows, do a <STRONG>wnoutrefresh</STRONG> on - its windows, call <STRONG>setsyx</STRONG>, and then call <STRONG>doupdate</STRONG>. + <STRONG>setsyx</STRONG> sets the virtual screen (<STRONG>newscr</STRONG>) cursor location to (<EM>y</EM>, <EM>x</EM>). + <STRONG>setsyx(-1,</STRONG> <STRONG>-1)</STRONG> is equivalent to <STRONG>leaveok(newscr,</STRONG> <STRONG>TRUE)</STRONG>. - Few applications will use this feature, most use <STRONG>wmove</STRONG> instead. + <STRONG>getsyx</STRONG> and <STRONG>setsyx</STRONG> are designed to be used by a function that + manipulates <EM>curses</EM> windows but seeks to avoid changing the cursor + position. Such a function would first call <STRONG>getsyx</STRONG>, modify its windows' + content, call <STRONG><A HREF="curs_refresh.3x.html">wnoutrefresh(3x)</A></STRONG> on them, call <STRONG>setsyx</STRONG>, then call + <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG>. + Few applications use this feature; most call <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG> instead. -</PRE><H3><a name="h3-ripoffline">ripoffline</a></H3><PRE> - <STRONG>ripoffline</STRONG> provides access to the same facility that <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG> uses - to reduce the size of the screen. <STRONG>ripoffline</STRONG> must be called before - <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> is called, to prepare these initial actions: - <STRONG>o</STRONG> If <EM>line</EM> is positive, a line is removed from the top of <STRONG>stdscr</STRONG>. +</PRE><H3><a name="h3-curs_set">curs_set</a></H3><PRE> + <STRONG>curs_set</STRONG> adjusts the cursor visibility to "invisible", "visible", "very + visible", as its argument is <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, respectively. It returns the + previous <EM>visibility</EM> if the requested one is supported, and <STRONG>ERR</STRONG> + otherwise. - <STRONG>o</STRONG> if <EM>line</EM> is negative, a line is removed from the bottom. - When the resulting initialization is done inside <STRONG>initscr</STRONG>, the routine - <STRONG>init</STRONG> (supplied by the user) is called with two arguments: +</PRE><H3><a name="h3-mvcur">mvcur</a></H3><PRE> + <STRONG>mvcur</STRONG> provides low-level cursor motion. It takes effect immediately, + rather than at the next refresh. Unlike the other low-level output + functions, which either write to the standard output stream or are + passed a function pointer to perform output, <STRONG>mvcur</STRONG> uses a file + descriptor derived from the output stream parameter of <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>. - <STRONG>o</STRONG> a window pointer to the one-line window that has been allocated and + One application of <STRONG>mvcur</STRONG> accompanies the temporary use of another + program to write to the terminal screen. For example, first call + <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> to ensure that the screen and the library's model of it are + up to date; then call <STRONG>reset_shell_mode</STRONG>; write to the screen with the + external application; call <STRONG>reset_prog_mode</STRONG>; and finally call <STRONG>mvcur(</STRONG>...<STRONG>,</STRONG> + ...<STRONG>,</STRONG> <STRONG>-1,</STRONG> <STRONG>-1)</STRONG> to move the terminal cursor to where <EM>curses</EM> thinks it is, + since the library has no knowledge of how the external application + moved it. - <STRONG>o</STRONG> an integer with the number of columns in the window. - Inside this initialization routine, the integer variables <STRONG>LINES</STRONG> and - <STRONG>COLS</STRONG> (defined in <STRONG><curses.h></STRONG>) are not guaranteed to be accurate and - <STRONG>wrefresh</STRONG> or <STRONG>doupdate</STRONG> must not be called. It is allowable to call - <STRONG>wnoutrefresh</STRONG> during the initialization routine. +</PRE><H3><a name="h3-napms">napms</a></H3><PRE> + <STRONG>napms</STRONG> sleeps for <EM>ms</EM> milliseconds. If <EM>ms</EM> exceeds 30,000 (thirty + seconds), <EM>ncurses</EM> caps it at that value. + - <STRONG>ripoffline</STRONG> can be called up to five times before calling <STRONG>initscr</STRONG> or - <STRONG>newterm</STRONG>. +</PRE><H3><a name="h3-ripoffline">ripoffline</a></H3><PRE> + <STRONG>ripoffline</STRONG> provides access to the same facility that <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG> uses + to reduce the size of the screen. The application must call <STRONG>ripoffline</STRONG> + before <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> so that the latter functions prepare + a <STRONG>stdscr</STRONG> of the correct size. + <STRONG>o</STRONG> If <EM>line</EM> is positive, <STRONG>ripoffline</STRONG> removes a line from the top of what + will become <STRONG>stdscr</STRONG>. -</PRE><H3><a name="h3-curs_set">curs_set</a></H3><PRE> - The <STRONG>curs_set</STRONG> routine sets the cursor state to invisible, normal, or - very visible for <STRONG>visibility</STRONG> equal to <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG> respectively. If the - terminal supports the <EM>visibility</EM> requested, the previous <EM>cursor</EM> state - is returned; otherwise, <STRONG>ERR</STRONG> is returned. + <STRONG>o</STRONG> If <EM>line</EM> is negative, <STRONG>ripoffline</STRONG> removes a line from the bottom of + what will become <STRONG>stdscr</STRONG>. + When <STRONG>initscr</STRONG> initializes <EM>curses</EM>, it calls the <EM>init</EM> function supplied to + <STRONG>ripoffline</STRONG> by the application with two arguments: -</PRE><H3><a name="h3-napms">napms</a></H3><PRE> - <STRONG>napms</STRONG> sleeps for <EM>ms</EM> milliseconds. If <EM>ms</EM> exceeds 30,000 (thirty - seconds), it is capped at that value. + <STRONG>o</STRONG> a pointer to the one-line <EM>WINDOW</EM> that it allocates, and + + <STRONG>o</STRONG> an integer with the number of columns in the window. + + Inside this <EM>init</EM> function, the values of the integer variables <STRONG>LINES</STRONG> + and <STRONG>COLS</STRONG> (see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>) are not guaranteed to be reliable; it + must not call <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG> or <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG>. A <STRONG><A HREF="curs_refresh.3x.html">wnoutrefresh(3x)</A></STRONG> call is + permissible. + + <STRONG>ripoffline</STRONG> can be called up to five times before <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Except for <STRONG>curs_set</STRONG>, these routines always return <STRONG>OK</STRONG>. + Except for <STRONG>curs_set</STRONG>, these functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on + failure. - <STRONG>curs_set</STRONG> returns the previous cursor state, or <STRONG>ERR</STRONG> if the requested - <EM>visibility</EM> is not supported. + <STRONG>curs_set</STRONG> returns the previous cursor visibility, and returns <STRONG>ERR</STRONG> if the + terminal type does not support the requested <EM>visibility</EM>. - X/Open defines no error conditions. In this implementation + <STRONG>napms</STRONG> always succeeds. - <STRONG>def_prog_mode</STRONG>, <STRONG>def_shell_mode</STRONG>, <STRONG>reset_prog_mode</STRONG>, <STRONG>reset_shell_mode</STRONG> - return an error if the terminal was not initialized, or if the I/O - call to obtain the terminal settings fails. + <STRONG>mvcur</STRONG> fails if the position (<EM>newrow</EM>, <EM>newcol</EM>) is outside the screen + boundaries. - <STRONG>ripoffline</STRONG> - returns an error if the maximum number of ripped-off lines exceeds - the maximum (5). + In <EM>ncurses</EM>, + + <STRONG>o</STRONG> <STRONG>def_prog_mode</STRONG>, <STRONG>def_shell_mode</STRONG>, <STRONG>reset_prog_mode</STRONG>, and + <STRONG>reset_shell_mode</STRONG> return <STRONG>ERR</STRONG> if the terminal was not initialized, or + if the operating system's function for obtaining terminal settings + fails. + + <STRONG>o</STRONG> <STRONG>ripoffline</STRONG> returns <STRONG>ERR</STRONG> if the accumulated quantity of ripped-off + lines would exceed the maximum (5). </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that <STRONG>getsyx</STRONG> is a macro, so <STRONG>&</STRONG> is not necessary before the variables - <EM>y</EM> and <EM>x</EM>. + <STRONG>getsyx</STRONG> is a macro; use of the <STRONG>&</STRONG> operator before its arguments is + unnecessary. + + The <STRONG>endwin</STRONG> function of both <EM>ncurses</EM> and SVr4 <EM>curses</EM> calls <STRONG>curs_set</STRONG> if + the latter has previously been called to set the cursor visibility to a + value other than normal; that is, either invisible or very visible. + There is no way for <EM>ncurses</EM> to determine the initial cursor visibility + to restore it. + + <EM>ncurses</EM> imposes a limit of 30 seconds on a delay requested of <STRONG>napms</STRONG>. + + While the <EM>init</EM> function called by <STRONG>ripoffline</STRONG> is specified to return an + <EM>int</EM>, <EM>ncurses</EM> pays no attention to its return value. - Older SVr4 man pages warn that the return value of <STRONG>curs_set</STRONG> "is - currently incorrect". This implementation gets it right, but it may be - unwise to count on the correctness of the return value anywhere else. + If <STRONG>ripoffline</STRONG> cannot allocate memory for the required <EM>WINDOW</EM> structure + backing the ripped-off line, it stores a null pointer to the <EM>WINDOW</EM> + pointer argument supplied by the <EM>init</EM> function the application + specifies. The application must check this argument for validity after + calling <STRONG>initscr</STRONG> and prior to performing <EM>curses</EM> operations on that + window. - Both <EM>ncurses</EM> and SVr4 will call <STRONG>curs_set</STRONG> in <STRONG>endwin</STRONG> if <STRONG>curs_set</STRONG> has been - called to make the cursor other than normal, i.e., either invisible or - very visible. There is no way for <EM>ncurses</EM> to determine the initial - cursor state to restore that. + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + In <EM>ncurses</EM>, <STRONG>mvcur</STRONG> accepts <STRONG>-1</STRONG> for either or both old coordinates. This + value tells <EM>ncurses</EM> that the old location is unknown, and that it must + use only absolute motion, as with the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>) capability, + rather than the least costly combination of absolute and relative + motion. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - The <EM>virtual</EM> <EM>screen</EM> functions <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> are not described in - X/Open Curses, Issue 4. All other functions are as described in X/Open - Curses. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + + The <EM>virtual</EM> <EM>screen</EM> functions <EM>setsyx</EM> and <EM>getsyx</EM> are not described in + X/Open Curses Issue 4. SVr4 documents each of them as returning an + <EM>int</EM>. This is misleading, as they are macros with no documented + semantics for returning values. + + All other functions are as described in X/Open Curses. It specifies no + error conditions for them, except as described for <EM>curs</EM><STRONG>_</STRONG><EM>set</EM> in section + "RETURN VALUE" above. + + The System V Interface Definition, Version 4 (1995), specified all of + these functions except <EM>curs</EM><STRONG>_</STRONG><EM>set</EM> as returning <EM>OK</EM>. - The SVr4 documentation describes <STRONG>setsyx</STRONG> and <STRONG>getsyx</STRONG> as having return - type int. This is misleading, as they are macros with no documented - semantics for the return value. + Older SVr4 man pages warn that the return value of <EM>curs</EM><STRONG>_</STRONG><EM>set</EM> "is + currently incorrect". This implementation gets it right, but counting + on its correctness anywhere else may be unwise. - If interrupted, <EM>ncurses</EM> restarts <STRONG>napms</STRONG>. That, and the limitation to 30 - seconds, are different from other implementations. + X/Open Curses specifies <EM>ripoffline</EM> as returning <EM>OK</EM> with no possibility + of failure ("[c]alls to <EM>ripoffline</EM> above this limit [five lines] have + no effect but report success"). + + X/Open Curses notes: + + After use of <EM>mvcur</EM>(), the model Curses maintains of the state of + the terminal might not match the actual state of the terminal. + An application should touch and refresh the window before + resuming conventional use of Curses. + + Both <EM>ncurses</EM> and SVr4 <EM>curses</EM> implement <EM>mvcur</EM> using the <EM>SCREEN</EM> object + allocated in either <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>. X/Open Curses states + that the old location must be given for <EM>mvcur</EM> to accommodate terminals + that lack absolute cursor positioning. + + If interrupted by a signal, <EM>ncurses</EM> restarts <EM>napms</EM>. That, and the + limitation to 30 seconds, differ from other implementations. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>, <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> +ncurses 6.6 2025-08-16 <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -221,13 +288,15 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF=" <li><a href="#h3-resetty_savetty">resetty, savetty</a></li> <li><a href="#h3-getsyx">getsyx</a></li> <li><a href="#h3-setsyx">setsyx</a></li> -<li><a href="#h3-ripoffline">ripoffline</a></li> <li><a href="#h3-curs_set">curs_set</a></li> +<li><a href="#h3-mvcur">mvcur</a></li> <li><a href="#h3-napms">napms</a></li> +<li><a href="#h3-ripoffline">ripoffline</a></li> </ul> </li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> diff --git a/doc/html/man/curs_legacy.3x.html b/doc/html/man/curs_legacy.3x.html index 22f78dddbcf9..ec4e4290d360 100644 --- a/doc/html/man/curs_legacy.3x.html +++ b/doc/html/man/curs_legacy.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 2007-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_legacy.3x,v 1.32 2024/03/16 15:35:01 tom Exp @ + * @Id: curs_legacy.3x,v 1.36 2025/02/15 18:43:02 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_legacy 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_legacy 3x 2025-02-15 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_legacy 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_legacy 3x 2025-02-15 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>getattrs</STRONG>, <STRONG>getbegx</STRONG>, <STRONG>getbegy</STRONG>, <STRONG>getcurx</STRONG>, <STRONG>getcury</STRONG>, <STRONG>getmaxx</STRONG>, <STRONG>getmaxy</STRONG>, <STRONG>getparx</STRONG>, <STRONG>getpary</STRONG> - get <EM>curses</EM> cursor and window coordinates or @@ -82,9 +80,9 @@ fit into a <STRONG>chtype</STRONG>, so <STRONG>wattr_get</STRONG> is the only way to obtain the color information. - Because <STRONG>getattrs</STRONG> returns the attributes in a single parameter, it - would not be possible for an application to distinguish that from - <STRONG>ERR</STRONG> (a <EM>-1</EM>). If the window parameter is null, <STRONG>getattrs</STRONG> returns + Because <STRONG>getattrs</STRONG> returns the attributes in a single parameter, it + would not be possible for an application to distinguish that from + <STRONG>ERR</STRONG> (a <EM>-1</EM>). If the window parameter is null, <STRONG>getattrs</STRONG> returns <STRONG>A_NORMAL</STRONG> (zero). <STRONG>o</STRONG> The <STRONG>getbegy</STRONG> and <STRONG>getbegx</STRONG> functions return the same data as <STRONG>getbegyx</STRONG>. @@ -97,21 +95,10 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Except as noted, these functions return an integer, or <STRONG>ERR</STRONG> if the + Except as noted, these functions return an integer, or <STRONG>ERR</STRONG> if the window parameter is null. -</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All of these interfaces are implemented as macros and functions. The - macros are suppressed (and only the functions provided) in an "opaque" - <EM>ncurses</EM> build, which defines the preprocessor symbol <STRONG>NCURSES_OPAQUE</STRONG>. - See section "ALTERNATE CONFIGURATIONS" in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. - - The standard forms such as <STRONG>getyx</STRONG> <EM>must</EM> be implemented as macros, and (in - this implementation) are defined in terms of the functions described - here, to avoid reliance on internal details of the <EM>WINDOW</EM> structure. - - </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> These functions were supported on Version 7, BSD or System V implementations. None of those implementations checked the window @@ -125,9 +112,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getyx.3x.html">curs_getyx(3x)</A></STRONG>, <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG> +ncurses 6.6 2025-02-15 <STRONG><A HREF="curs_legacy.3x.html">curs_legacy(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -135,7 +120,6 @@ ncurses 6.5 2024-03-16 <STRONG><A HREF=" <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> -<li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> diff --git a/doc/html/man/curs_memleaks.3x.html b/doc/html/man/curs_memleaks.3x.html index 085e3aba91d8..975ab0d92327 100644 --- a/doc/html/man/curs_memleaks.3x.html +++ b/doc/html/man/curs_memleaks.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_memleaks 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_memleaks 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_memleaks 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_memleaks 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>exit_curses</STRONG>, <STRONG>exit_terminfo</STRONG> - check for memory leaks in <EM>curses</EM> @@ -76,7 +74,7 @@ functions which free those chunks of memory, simplifying the process of memory-leak checking. - Some of the functions are named with a "_nc_" prefix because they are + Some of the functions are named with a "_nc_" prefix because they are not intended for use in the non-debugging library: <STRONG>_nc_freeall</STRONG> @@ -85,11 +83,11 @@ <STRONG>_nc_free_and_exit</STRONG> This frees the memory allocated by <EM>ncurses</EM> (like <STRONG>_nc_freeall</STRONG>), and exits the program. It is preferred over <STRONG>_nc_freeall</STRONG> since some of - that memory may be required to keep the application running. + that memory may be required to keep the application running. Simply exiting (with the given exit-code) is safer. <STRONG>_nc_free_tinfo</STRONG> - Use this function if only the low-level terminfo functions (and + Use this function if only the low-level terminfo functions (and corresponding library) are used. Like <STRONG>_nc_free_and_exit</STRONG>, it exits the program after freeing memory. @@ -115,10 +113,10 @@ In any implementation of X/Open Curses, an application can free part of the memory allocated by curses: - <STRONG>o</STRONG> The portable part of <STRONG>exit_curses</STRONG> can be freed using <STRONG>delscreen</STRONG>, + <STRONG>o</STRONG> The portable part of <STRONG>exit_curses</STRONG> can be freed using <STRONG>delscreen</STRONG>, passing the <EM>SCREEN</EM> pointer returned by <STRONG>newterm</STRONG>. - In some implementations, there is a global variable <STRONG>sp</STRONG> which could + In some implementations, there is a global variable <STRONG>sp</STRONG> which could be used, e.g., if the screen were only initialized using <STRONG>initscr</STRONG>. <STRONG>o</STRONG> The portable part of <STRONG>exit_terminfo</STRONG> can be freed using <STRONG>del_curterm</STRONG>. @@ -130,9 +128,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_mouse.3x.html b/doc/html/man/curs_mouse.3x.html index cdb42f278832..399dbbd4978c 100644 --- a/doc/html/man/curs_mouse.3x.html +++ b/doc/html/man/curs_mouse.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,94 +28,108 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_mouse.3x,v 1.98 2024/04/20 19:02:07 tom Exp @ + * @Id: curs_mouse.3x,v 1.131 2025/11/12 01:06:36 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_mouse 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_mouse 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_mouse 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_mouse 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>has_mouse</STRONG>, <STRONG>getmouse</STRONG>, <STRONG>ungetmouse</STRONG>, <STRONG>mousemask</STRONG>, <STRONG>wenclose</STRONG>, <STRONG>mouse_trafo</STRONG>, - <STRONG>wmouse_trafo</STRONG>, <STRONG>mouseinterval</STRONG> - get mouse events in <EM>curses</EM> + <STRONG>wmouse_trafo</STRONG>, <STRONG>mouseinterval</STRONG>, <STRONG>mmask_t</STRONG>, <STRONG>MEVENT</STRONG> - get mouse events in + <EM>ncurses</EM> </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> + <EM>/*</EM> <EM>data</EM> <EM>types</EM> <EM>*/</EM> <STRONG>typedef</STRONG> <STRONG>unsigned</STRONG> <STRONG>long</STRONG> <STRONG>mmask_t;</STRONG> <STRONG>typedef</STRONG> <STRONG>struct</STRONG> <STRONG>{</STRONG> - <STRONG>short</STRONG> <STRONG>id;</STRONG> <EM>/*</EM> <EM>ID</EM> <EM>to</EM> <EM>distinguish</EM> <EM>multiple</EM> <EM>devices</EM> <EM>*/</EM> - <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>y,</STRONG> <STRONG>z;</STRONG> <EM>/*</EM> <EM>event</EM> <EM>coordinates</EM> <EM>*/</EM> - <STRONG>mmask_t</STRONG> <STRONG>bstate;</STRONG> <EM>/*</EM> <EM>button</EM> <EM>state</EM> <EM>bits</EM> <EM>*/</EM> + <STRONG>short</STRONG> <STRONG>id;</STRONG> <EM>/*</EM> <EM>ID</EM> <EM>to</EM> <EM>distinguish</EM> <EM>multiple</EM> <EM>devices</EM> <EM>*/</EM> + <STRONG>int</STRONG> <STRONG>x,</STRONG> <STRONG>y,</STRONG> <STRONG>z;</STRONG> <EM>/*</EM> <EM>event</EM> <EM>coordinates</EM> <EM>*/</EM> + <STRONG>mmask_t</STRONG> <STRONG>bstate;</STRONG> <EM>/*</EM> <EM>button</EM> <EM>state</EM> <EM>bits</EM> <EM>*/</EM> <STRONG>}</STRONG> <STRONG>MEVENT;</STRONG> + <EM>/*</EM> <EM>functions</EM> <EM>*/</EM> <STRONG>bool</STRONG> <STRONG>has_mouse(void);</STRONG> - <STRONG>mmask_t</STRONG> <STRONG>mousemask(mmask_t</STRONG> <EM>newmask</EM><STRONG>,</STRONG> <STRONG>mmask_t</STRONG> <STRONG>*</STRONG><EM>oldmask</EM><STRONG>);</STRONG> + <STRONG>mmask_t</STRONG> <STRONG>mousemask(mmask_t</STRONG> <EM>new-mask</EM><STRONG>,</STRONG> <STRONG>mmask_t</STRONG> <STRONG>*</STRONG> <EM>old-mask</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>getmouse(MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>ungetmouse(MEVENT</STRONG> <STRONG>*</STRONG><EM>event</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>getmouse(MEVENT</STRONG> <STRONG>*</STRONG> <EM>event</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>ungetmouse(MEVENT</STRONG> <STRONG>*</STRONG> <EM>event</EM><STRONG>);</STRONG> - <STRONG>bool</STRONG> <STRONG>wenclose(const</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> + <STRONG>bool</STRONG> <STRONG>wenclose(const</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> - <STRONG>bool</STRONG> <STRONG>mouse_trafo(int*</STRONG> <EM>pY</EM><STRONG>,</STRONG> <STRONG>int*</STRONG> <EM>pX</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>to</EM><STRONG>_</STRONG><EM>screen</EM><STRONG>);</STRONG> - <STRONG>bool</STRONG> <STRONG>wmouse_trafo(const</STRONG> <STRONG>WINDOW*</STRONG> <EM>win</EM><STRONG>,</STRONG> - <STRONG>int*</STRONG> <EM>pY</EM><STRONG>,</STRONG> <STRONG>int*</STRONG> <EM>pX</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>to</EM><STRONG>_</STRONG><EM>screen</EM><STRONG>);</STRONG> + <STRONG>bool</STRONG> <STRONG>mouse_trafo(int</STRONG> <STRONG>*</STRONG> <EM>pY</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>pX</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>to-screen</EM><STRONG>);</STRONG> + <STRONG>bool</STRONG> <STRONG>wmouse_trafo(const</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> + <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>pY</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>pX</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>to-screen</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>mouseinterval(int</STRONG> <EM>erval</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These functions provide an interface to mouse events from <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. - Mouse events are represented by <STRONG>KEY_MOUSE</STRONG> pseudo-key values in the - <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> input stream. + <EM>ncurses</EM> provides an interface to the mouse or other pointing device. + An application can register its interest in such events; the library + then exposes the availability of a mouse event via an <EM>input</EM> <EM>character</EM> + <EM>reading</EM> <EM>function</EM>: this is <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> in the non-wide character <EM>curses</EM> + API and <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG> in the wide character API. A queue distinct from + that used for keyboard events accumulates the details of mouse events. + The input character reading function reports the <STRONG>KEY_MOUSE</STRONG> key code + when a mouse event is available for collection. A single mouse event + queue serves all windows associated with the screen. + + The <EM>MEVENT</EM> structure describes a mouse event. Its <EM>y</EM> and <EM>x</EM> coordinates + are screen-, not window-, relative. The <EM>bstate</EM> member has exactly one + bit set indicating the event type. + + <EM>ncurses</EM> ignores mouse events when input is in canonical ("cooked") + mode, and produces an error beep when they occur while the library + simulates canonical mode in a window, as with <STRONG><A HREF="curs_getstr.3x.html">getstr(3x)</A></STRONG> (wide- + character API users: <STRONG><A HREF="curs_get_wstr.3x.html">get_wstr(3x)</A></STRONG>), which expects a line feed to + terminate its input loop. </PRE><H3><a name="h3-has_mouse">has_mouse</a></H3><PRE> - The <STRONG>has_mouse</STRONG> function returns <STRONG>TRUE</STRONG> if the mouse driver has been - successfully initialized, and <STRONG>FALSE</STRONG> otherwise. - - Mouse events are ignored when input is in cooked mode, and cause an - error beep when cooked mode is being simulated in a window by a - function such as <STRONG>getstr</STRONG> that expects a linefeed for input-loop - termination. + The terminal type or operating system interface must support the + encoding of mouse events. <STRONG>has_mouse</STRONG> returns <STRONG>TRUE</STRONG> if <EM>ncurses</EM>'s mouse + driver initialized successfully, and <STRONG>FALSE</STRONG> otherwise. </PRE><H3><a name="h3-mousemask">mousemask</a></H3><PRE> - To make mouse events visible, use the <STRONG>mousemask</STRONG> function. This sets - the mouse events to be reported. By default, no mouse events are - reported. + Use <STRONG>mousemask</STRONG> to select the varieties of mouse event your application + wishes to receive. By default, <EM>ncurses</EM> reports no mouse events. - <STRONG>o</STRONG> The function returns an updated copy of <EM>newmask</EM> to indicate which - of the specified mouse events can be reported. + <STRONG>o</STRONG> The function returns an updated copy of <EM>new-mask</EM> indicating which + event types of interest are reportable by the terminal's mouse + protocol. - If the screen has not been initialized, or if the terminal does not - support mouse-events, this function returns 0. + If the screen is not initialized, or the terminal interface does + not report mouse events, <STRONG>mousemask</STRONG> returns 0. - <STRONG>o</STRONG> If <EM>oldmask</EM> is non-<STRONG>NULL</STRONG>, this function fills the indicated location - with the previous value of the current screen's mouse event mask. + <STRONG>o</STRONG> If <EM>old-mask</EM> is not a null pointer, <STRONG>mousemask</STRONG> stores the previous + value of the screen's mouse event mask there. - As a side effect, setting a zero mouse mask may turn off the mouse - pointer; setting a nonzero mask may turn it on. Whether this happens - is device-dependent. + As a side effect, setting a zero mouse mask may turn off the mouse + cursor; setting a nonzero mask may turn it on. Whether this happens is + device-dependent. </PRE><H3><a name="h3-Mouse-Events">Mouse Events</a></H3><PRE> - Here are the mouse event type masks which may be defined: + Several mouse event types may be selected; construct a mask by + logically "or"-ing their values. <STRONG>Name</STRONG> <STRONG>Description</STRONG> ------------------------------------------------------------------------ @@ -149,93 +163,83 @@ <STRONG>BUTTON5_DOUBLE_CLICKED</STRONG> mouse button 5 double clicked <STRONG>BUTTON5_TRIPLE_CLICKED</STRONG> mouse button 5 triple clicked ------------------------------------------------------------------------ - <STRONG>BUTTON_SHIFT</STRONG> shift was down during button state change - <STRONG>BUTTON_CTRL</STRONG> control was down during button state change - <STRONG>BUTTON_ALT</STRONG> alt was down during button state change + <STRONG>BUTTON_SHIFT</STRONG> a shift key was down during button state + change + <STRONG>BUTTON_CTRL</STRONG> a control key was down during button state + change + <STRONG>BUTTON_ALT</STRONG> an alt key was down during button state change <STRONG>ALL_MOUSE_EVENTS</STRONG> report all button state changes <STRONG>REPORT_MOUSE_POSITION</STRONG> report mouse movement ------------------------------------------------------------------------ </PRE><H3><a name="h3-getmouse">getmouse</a></H3><PRE> - Once a class of mouse events has been made visible in a window, calling - the <STRONG>wgetch</STRONG> function on that window may return <STRONG>KEY_MOUSE</STRONG> as an indicator - that a mouse event has been queued. To read the event data and pop the - event off the queue, call <STRONG>getmouse</STRONG>. This function will return <STRONG>OK</STRONG> if a - mouse event is actually visible in the given window, <STRONG>ERR</STRONG> otherwise. - When <STRONG>getmouse</STRONG> returns <STRONG>OK</STRONG>, the data deposited as y and x in the event - structure coordinates will be screen-relative character-cell - coordinates. The returned state mask will have exactly one bit set to - indicate the event type. The corresponding data in the queue is marked - invalid. A subsequent call to <STRONG>getmouse</STRONG> will retrieve the next older - item from the queue. + When a window is configured to report a non-empty set of event types, + calling the input character reading function on that window may return + <STRONG>KEY_MOUSE</STRONG> to indicate availability of an enqueued mouse event. To read + the event data and remove it from the queue, call <STRONG>getmouse</STRONG>, which + returns <STRONG>OK</STRONG> if a mouse event is visible in the given window and <STRONG>ERR</STRONG> + otherwise. When <STRONG>getmouse</STRONG> returns <STRONG>OK</STRONG>, it deposits data describing the + mouse event in the <EM>event</EM> pointer you supply. A subsequent <STRONG>getmouse</STRONG> + call retrieves the next older event from the queue. </PRE><H3><a name="h3-ungetmouse">ungetmouse</a></H3><PRE> - The <STRONG>ungetmouse</STRONG> function behaves analogously to <STRONG>ungetch</STRONG>. It pushes a - <STRONG>KEY_MOUSE</STRONG> event onto the input queue, and associates with that event - the given state data and screen-relative character-cell coordinates. + <STRONG>ungetmouse</STRONG> behaves analogously to <STRONG><A HREF="curs_util.3x.html">ungetch(3x)</A></STRONG>. It pushes a <STRONG>KEY_MOUSE</STRONG> + event onto the screen's input queue, and <EM>event</EM> onto the mouse event + queue. </PRE><H3><a name="h3-wenclose">wenclose</a></H3><PRE> - The <STRONG>wenclose</STRONG> function tests whether a given pair of screen-relative - character-cell coordinates is enclosed by a given window, returning - <STRONG>TRUE</STRONG> if it is and <STRONG>FALSE</STRONG> otherwise. It is useful for determining what - subset of the screen windows enclose the location of a mouse event. + <STRONG>wenclose</STRONG> returns <STRONG>TRUE</STRONG> if the pair of screen-relative coordinates (<EM>y</EM>, <EM>x</EM>) + is enclosed by the given window <EM>win</EM>, and <STRONG>FALSE</STRONG> otherwise. If <EM>win</EM> is a + pad, <STRONG>wenclose</STRONG> uses its most recent screen coordinates as specified in a + <STRONG><A HREF="curs_pad.3x.html">prefresh(3x)</A></STRONG> or <STRONG><A HREF="curs_pad.3x.html">pnoutrefresh(3x)</A></STRONG> call. - If the parameter is a pad, <STRONG>wenclose</STRONG> uses the most recent screen - coordinates used for this pad in <STRONG><A HREF="curs_pad.3x.html">prefresh(3x)</A></STRONG> or <STRONG><A HREF="curs_pad.3x.html">pnoutrefresh(3x)</A></STRONG>. + <STRONG>wenclose</STRONG> is useful for determining what subset of the screen's windows + encloses the location of a mouse event; it is otherwise independent of + the <EM>ncurses</EM> mouse API. </PRE><H3><a name="h3-wmouse_trafo">wmouse_trafo</a></H3><PRE> - The <STRONG>wmouse_trafo</STRONG> function transforms a given pair of coordinates from - <STRONG>stdscr</STRONG>-relative coordinates to coordinates relative to the given window - or vice versa. The resulting <STRONG>stdscr</STRONG>-relative coordinates are not - always identical to screen coordinates due to the mechanism to reserve - lines on top or bottom of the screen for other purposes (see the - <STRONG><A HREF="curs_kernel.3x.html">ripoffline(3x)</A></STRONG> and <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG> calls, for example). - - <STRONG>o</STRONG> If the parameter <EM>to</EM><STRONG>_</STRONG><EM>screen</EM> is <STRONG>TRUE</STRONG>, the pointers <EM>pY,</EM> <EM>pX</EM> must - reference the coordinates of a location inside the window <EM>win</EM>. - They are converted to <STRONG>stdscr</STRONG>-relative coordinates and returned - through the pointers. If the conversion was successful, the - function returns <STRONG>TRUE</STRONG>. - - If one of the parameters was <STRONG>NULL</STRONG> or the location is not inside the - window, <STRONG>FALSE</STRONG> is returned. - - <STRONG>o</STRONG> If <EM>to</EM><STRONG>_</STRONG><EM>screen</EM> is <STRONG>FALSE</STRONG>, the pointers <EM>pY,</EM> <EM>pX</EM> must reference - <STRONG>stdscr</STRONG>-relative coordinates. They are converted to window-relative - coordinates if the window <EM>win</EM> encloses this point. In this case - the function returns <STRONG>TRUE</STRONG>. + <STRONG>wmouse_trafo</STRONG> transforms the given pair of coordinate pointers (<EM>pY</EM>, <EM>pX</EM>) + from a <EM>win</EM>-relative basis to a screen-relative one or <EM>vice</EM> <EM>versa</EM>, as + <EM>to-screen</EM> is <STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>, respectively. <STRONG>stdscr</STRONG>-relative coordinates + are not always identical to screen coordinates: <EM>curses</EM> supports + reservation of screen lines at the top and/or bottom for other + purposes; see <STRONG><A HREF="curs_kernel.3x.html">ripoffline(3x)</A></STRONG> and <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG>. - If one of the parameters is <STRONG>NULL</STRONG> or the point is not inside the - window, <STRONG>FALSE</STRONG> is returned. + If <EM>to-screen</EM> <EM>is</EM> <STRONG>TRUE</STRONG> and the pointers (<EM>pY</EM>, <EM>pX</EM>) reference coordinates + inside <EM>win</EM>, <EM>ncurses</EM> updates their values to <STRONG>stdscr</STRONG>-relative coordinates + and returns <STRONG>TRUE</STRONG>. If either <EM>pY</EM> or <EM>pX</EM> is a null pointer, or (<EM>pY</EM>, <EM>pX</EM>) is + not inside <EM>win</EM>, <STRONG>wmouse_trafo</STRONG> returns <STRONG>FALSE</STRONG>. - The referenced coordinates are only replaced by the converted - coordinates if the transformation was successful. + If <EM>to-screen</EM> <EM>is</EM> <STRONG>FALSE</STRONG> and the pointers (<EM>pY</EM>, <EM>pX</EM>) reference coordinates + inside <STRONG>stdscr</STRONG>, <EM>ncurses</EM> updates their values to <EM>win</EM>-relative coordinates + and returns <STRONG>TRUE</STRONG>. If either <EM>pY</EM> or <EM>pX</EM> is a null pointer, or (<EM>pY</EM>, <EM>pX</EM>) is + not inside <STRONG>stdscr</STRONG>, <STRONG>wmouse_trafo</STRONG> returns <STRONG>FALSE</STRONG>. </PRE><H3><a name="h3-mouse_trafo">mouse_trafo</a></H3><PRE> - The <STRONG>mouse_trafo</STRONG> function performs the same translation as <STRONG>wmouse_trafo</STRONG>, - using <STRONG>stdscr</STRONG> for <EM>win</EM>. + <STRONG>mouse_trafo</STRONG> applies the <STRONG>wmouse_trafo</STRONG> translation to <STRONG>stdscr</STRONG>. If no + screen lines are reserved by <STRONG><A HREF="curs_kernel.3x.html">ripoffline(3x)</A></STRONG> or <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG>, this is + the identity transformation. </PRE><H3><a name="h3-mouseinterval">mouseinterval</a></H3><PRE> - The <STRONG>mouseinterval</STRONG> function sets the maximum time (in thousands of a - second) that can elapse between press and release events for them to be - resolved as a <EM>click</EM>. An application might interpret button press and - release events separated by more than the mouse interval as a "long - press", or, with motion, as a "drag". - - Calling <STRONG>mouseinterval(0)</STRONG> disables click resolution. When <EM>ncurses</EM> - detects a mouse event, it awaits further input activity up to this - interval, and then checks for a subsequent mouse event which can be - combined with the first event. If the timeout expires without input - activity (which would happen with a zero interval), then no click - resolution will occur. - - This function returns the previous interval value. Use + <STRONG>mouseinterval</STRONG> sets the maximum time (in thousandths of a second) that + can elapse between press and release events for them to be resolved as + a <EM>click</EM>. An application might interpret button press and release + events separated by more than the mouse interval as a "long press", or, + with motion, as a "drag". + + When <EM>ncurses</EM> detects a mouse event, it awaits further input activity up + to this interval, and then checks for a subsequent mouse event which + can be combined with the first event. If the timeout expires without + input activity, then no click resolution occurs. Calling + <STRONG>mouseinterval(0)</STRONG> disables click resolution. + + <STRONG>mouseinterval</STRONG> returns the previous interval value. Use <STRONG>mouseinterval(-1)</STRONG> to obtain the interval without altering it. The mouse interval is set to one sixth of a second when the @@ -255,24 +259,24 @@ <STRONG>o</STRONG> the mask of reportable events is zero, - <STRONG>o</STRONG> a mouse event was detected that does not match the mask, + <STRONG>o</STRONG> a mouse event was detected that does not match the mask, or - <STRONG>o</STRONG> or if no more events remain in the queue. + <STRONG>o</STRONG> no more events remain in the queue. - <STRONG>ungetmouse</STRONG> returns an error if the event queue is full. + <STRONG>ungetmouse</STRONG> returns <STRONG>ERR</STRONG> if the event queue is full. <STRONG>mousemask</STRONG> returns the mask of reportable events. - <STRONG>mouseinterval</STRONG> returns the previous interval value, unless the terminal - was not initialized. In that case, it returns the maximum interval + <STRONG>mouseinterval</STRONG> returns the previous interval value, unless the terminal + was not initialized. In that case, it returns the maximum interval value (166). </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - The order of the <STRONG>MEVENT</STRONG> structure members is not guaranteed. + The order of the <STRONG>MEVENT</STRONG> structure members is not guaranteed. Additional fields may be added to the structure in the future. - Under <EM>ncurses</EM>, these calls are implemented using either <EM>xterm</EM>'s built- + Under <EM>ncurses</EM>, these calls are implemented using either <EM>xterm</EM>'s built- in mouse-tracking API or platform-specific drivers including <STRONG>o</STRONG> Alessandro Rubini's gpm server @@ -281,35 +285,40 @@ <STRONG>o</STRONG> OS/2 EMX - If you are using an unsupported configuration, mouse events will not be - visible to <EM>ncurses</EM> (and the <STRONG>mousemask</STRONG> function will always return <STRONG>0</STRONG>). + If you are using an unsupported configuration, mouse events are not + visible to <EM>ncurses</EM> (and the <STRONG>mousemask</STRONG> function always returns <STRONG>0</STRONG>). - If the <EM>terminfo</EM> entry contains a <STRONG>XM</STRONG> string, this is used in the <EM>xterm</EM> - mouse driver to control the way the terminal is initialized for mouse - operation. The default, if <STRONG>XM</STRONG> is not found, corresponds to private - mode 1000 of <EM>xterm:</EM> + If the terminal type possesses the (nonstandard) <EM>terminfo</EM> string + capability <STRONG>XM</STRONG>, <EM>ncurses</EM>'s <EM>xterm</EM> mouse driver uses it when initializing + the terminal for mouse operation. The default, if <STRONG>XM</STRONG> is not found, + corresponds to private mode 1000 of <EM>xterm</EM>. \E[?1000%?%p1%{1}%=%th%el%; - The mouse driver also recognizes a newer <EM>xterm</EM> private mode 1006, e.g., + <EM>ncurses</EM> also recognizes <EM>xterm</EM>'s newer private mode 1006. \E[?1006;1000%?%p1%{1}%=%th%el%; - The <EM>z</EM> member in the event structure is not presently used. It is - intended for use with touch screens (which may be pressure-sensitive) + The <EM>id</EM> member of the mouse event structure is not presently used; no + terminal type or operating system interface supports reporting events + from distinguishable pointing devices. If you synthesize an <EM>MEVENT</EM>, + use an <EM>id</EM> of 0. + + The <EM>z</EM> member of the mouse event structure is not presently used. It is + intended for use with touch screens (which may be pressure-sensitive) or with 3D-mice/trackballs/power gloves. - The <STRONG>ALL_MOUSE_EVENTS</STRONG> class does not include <STRONG>REPORT_MOUSE_POSITION</STRONG>. - They are distinct. For example, in <EM>xterm</EM>, wheel/scrolling mice send - position reports as a sequence of presses of buttons 4 or 5 without + The <STRONG>ALL_MOUSE_EVENTS</STRONG> class does not include <STRONG>REPORT_MOUSE_POSITION</STRONG>. + They are distinct. For example, in <EM>xterm</EM>, wheel/scrolling mice send + position reports as a sequence of presses of buttons 4 or 5 without matching button-releases. </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - These functions were designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and are not found in - SVr4 <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous curses - implementation. (SVr4 <EM>curses</EM> did have a <EM>getmouse</EM> function, which took - no argument and returned a different type.) + These functions are <EM>ncurses</EM> extensions, and are not found in SVr4 + <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> implementation. + (SVr4 <EM>curses</EM> did have a <EM>getmouse</EM> function, which took no argument and + returned an <EM>unsigned</EM> <EM>long</EM>.) </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> @@ -320,15 +329,17 @@ "ALTERNATE CONFIGURATIONS" of <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. The following values may be specified. - 1 has definitions for reserved events. The mask uses 28 bits. + <STRONG>1</STRONG> has definitions for reserved events. The mask uses 28 bits. - 2 adds definitions for button 5, removes the definitions for + <STRONG>2</STRONG> adds definitions for button 5, removes the definitions for reserved events. The mask uses 29 bits. - SVr4 <EM>curses</EM> had support for the mouse in a variant of <STRONG>xterm(1)</STRONG>. It is + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr4 (1989) added mouse support to its variant of <STRONG>xterm(1)</STRONG>. It is mentioned in a few places, with little supporting documentation. - <STRONG>o</STRONG> Its "libcurses" manual page lists functions for this feature + <STRONG>o</STRONG> Its "libcurses" manual page lists functions for this feature prototyped in <EM>curses.h</EM>. extern int mouse_set(long int); @@ -347,21 +358,21 @@ <STRONG>mouse_info</STRONG> <STRONG>minfo</STRONG> <STRONG>Mi</STRONG> Mouse status information <STRONG>req_mouse_pos</STRONG> <STRONG>reqmp</STRONG> <STRONG>RQ</STRONG> Request mouse position report - <STRONG>o</STRONG> The interface made assumptions (as does <EM>ncurses</EM>) about the escape + <STRONG>o</STRONG> The interface made assumptions (as does <EM>ncurses</EM>) about the escape sequences sent to and received from the terminal. - For instance, the SVr4 <EM>curses</EM> library used the <STRONG>get_mouse</STRONG> capability - to tell the terminal which mouse button events it should send, - passing the mouse-button bit mask to the terminal. Also, it could - ask the terminal where the mouse was using the <STRONG>req_mouse_pos</STRONG> - capability. + For instance, the SVr4 <EM>curses</EM> library used the <STRONG>get_mouse</STRONG> (<STRONG>getm</STRONG>) + capability to tell the terminal which mouse button events it should + send, passing the mouse-button bit mask to the terminal. Also, it + could ask the terminal where the mouse was using the <STRONG>req_mouse_pos</STRONG> + (<STRONG>reqmp</STRONG>) capability. Those features required a terminal program that had been modified to work with SVr4 <EM>curses</EM>. They were not part of the X Consortium's <EM>xterm</EM>. - When developing the <EM>xterm</EM> mouse support for <EM>ncurses</EM> in September 1995, - Eric Raymond was uninterested in using the same interface due to its + When developing the <EM>xterm</EM> mouse support for <EM>ncurses</EM> in September 1995, + Eric Raymond was uninterested in using the same interface due to its lack of documentation. Later, in 1998, Mark Hesseling provided support in <EM>PDCurses</EM> 2.3 using the SVr4 interface. <EM>PDCurses</EM>, however, does not use video terminals, making it unnecessary to be concerned about @@ -369,32 +380,32 @@ </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE> - Mouse events from <EM>xterm</EM> are <EM>not</EM> ignored in cooked mode if they have - been enabled by <STRONG>mousemask</STRONG>. Instead, the <EM>xterm</EM> mouse report sequence - appears in the string read. - - Mouse event reports from <EM>xterm</EM> are not detected correctly in a window - with keypad application mode disabled, since they are interpreted as a - variety of function key. Set the terminal's <EM>terminfo</EM> capability <STRONG>kmous</STRONG> - to "\E[M" (the beginning of the response from <EM>xterm</EM> for mouse clicks). - Other values of <STRONG>kmous</STRONG> are permitted under the same assumption, that is, - the report begins with that sequence. + Mouse events from <EM>xterm</EM> are <EM>not</EM> ignored in canonical ("cooked") mode if + they have been enabled by <STRONG>mousemask</STRONG>. Instead, the <EM>xterm</EM> mouse report + sequence appears in the string read. + + An <EM>ncurses</EM> window must enable <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> to correctly receive mouse + event reports from <EM>xterm</EM> since they are encoded like function keys. + Set the terminal's <EM>terminfo</EM> capability <STRONG>key_mouse</STRONG> (<STRONG>kmous</STRONG>) to "\E[M" (the + beginning of the response from <EM>xterm</EM> for mouse clicks). Other values + of <STRONG>key_mouse</STRONG> are permitted under the same assumption -- that is, a + mouse report begins with the value of the <STRONG>key_mouse</STRONG> (<STRONG>kmous</STRONG>) string + capability. Because there are no standard response sequences that serve to identify terminals supporting the <EM>xterm</EM> mouse protocol, <EM>ncurses</EM> assumes that if - <STRONG>kmous</STRONG> is defined in the terminal description, or if the terminal type's - primary name or aliases contain the string "xterm", then the terminal - may send mouse events. The <STRONG>kmous</STRONG> capability is checked first, allowing - use of newer <EM>xterm</EM> mouse protocols, such as its private mode 1006. + <STRONG>key_mouse</STRONG> (<STRONG>kmous</STRONG>) is defined in the terminal description, or if the + terminal type's primary name or aliases contain the string "xterm", + then the terminal may send mouse events. <EM>ncurses</EM> checks the <STRONG>kmous</STRONG> cap- + code first, allowing use of newer <EM>xterm</EM> mouse protocols, such as its + private mode 1006. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>, <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -417,6 +428,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF= <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-BUGS">BUGS</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> diff --git a/doc/html/man/curs_move.3x.html b/doc/html/man/curs_move.3x.html index bbab2b871ff3..a530ab005d29 100644 --- a/doc/html/man/curs_move.3x.html +++ b/doc/html/man/curs_move.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_move.3x,v 1.40 2024/04/27 17:56:05 tom Exp @ + * @Id: curs_move.3x,v 1.63 2025/04/05 22:08:55 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_move 3x 2024-04-27 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_move 3x 2025-04-05 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_move 3x 2024-04-27 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_move 3x 2025-04-05 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>move</STRONG>, <STRONG>wmove</STRONG> - move cursor in a <EM>curses</EM> window @@ -54,23 +52,26 @@ <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> <STRONG>int</STRONG> <STRONG>move(int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wmove(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wmove(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> <STRONG>wmove</STRONG> relocates the cursor associated with the <EM>curses</EM> window <EM>win</EM> to line <EM>y</EM> and column <EM>x</EM>. The terminal's cursor does not move until <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> is called. The position (<EM>y</EM>, <EM>x</EM>) is relative to the upper - left-hand corner of the window, which has coordinates (0, 0). - <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> describes the <STRONG>move</STRONG> variant of this function. + left-hand corner of the window, which has coordinates (0, 0). <STRONG>move</STRONG> + similarly moves the cursor in the <STRONG>stdscr</STRONG> window. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. In <EM>ncurses</EM>, + these functions fail if - They fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>wmove</STRONG> fails if its <EM>WINDOW</EM> pointer argument is <STRONG>NULL</STRONG>. + <STRONG>o</STRONG> (for <STRONG>wmove</STRONG>) <EM>win</EM> is a null pointer, or + + <STRONG>o</STRONG> the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> @@ -78,15 +79,21 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced these functions. +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> -ncurses 6.5 2024-04-27 <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG> +ncurses 6.6 2025-04-05 <STRONG><A HREF="curs_move.3x.html">curs_move(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -96,6 +103,7 @@ ncurses 6.5 2024-04-27 <STRONG><A HREF <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_opaque.3x.html b/doc/html/man/curs_opaque.3x.html index 50bb9ee64e91..88028441ca1f 100644 --- a/doc/html/man/curs_opaque.3x.html +++ b/doc/html/man/curs_opaque.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2020-2023,2024 Thomas E. Dickey * + * Copyright 2020-2024,2025 Thomas E. Dickey * * Copyright 2007-2014,2015 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_opaque.3x,v 1.43 2024/03/16 15:35:01 tom Exp @ + * @Id: curs_opaque.3x,v 1.50 2025/02/15 19:36:24 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_opaque 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_opaque 3x 2025-02-15 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_opaque 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_opaque 3x 2025-02-15 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>is_cleared</STRONG>, <STRONG>is_idlok</STRONG>, <STRONG>is_idcok</STRONG>, <STRONG>is_immedok</STRONG>, <STRONG>is_keypad</STRONG>, <STRONG>is_leaveok</STRONG>, <STRONG>is_nodelay</STRONG>, <STRONG>is_notimeout</STRONG>, <STRONG>is_pad</STRONG>, <STRONG>is_scrollok</STRONG>, <STRONG>is_subwin</STRONG>, <STRONG>is_syncok</STRONG>, @@ -124,12 +122,12 @@ returns the delay timeout set by <STRONG><A HREF="wtimeout.3x.html">wtimeout(3x)</A></STRONG>. <STRONG>wgetparent</STRONG> - returns the parent <EM>WINDOW</EM> pointer for subwindows, or <STRONG>NULL</STRONG> for + returns the parent <EM>WINDOW</EM> pointer for subwindows, or <EM>NULL</EM> for windows having no parent. <STRONG>wgetscrreg</STRONG> - stores the the top and bottom rows for the scrolling margin set - by <STRONG><A HREF="curs_outopts.3x.html">wsetscrreg(3x)</A></STRONG> in the corresponding arguments, returning <STRONG>ERR</STRONG> + stores the top and bottom rows for the scrolling margin set by + <STRONG><A HREF="curs_outopts.3x.html">wsetscrreg(3x)</A></STRONG> in the corresponding arguments, returning <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon successful completion. @@ -142,20 +140,23 @@ function documented in this page. +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + These functions originated with <EM>ncurses</EM>. + + </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines are specific to <EM>ncurses</EM>. They were not supported on - Version 7, BSD or System V implementations. It is recommended that any - code depending on <EM>ncurses</EM> extensions be conditioned using - <STRONG>NCURSES_VERSION</STRONG>. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + + NetBSD <EM>curses</EM> since 10.1 (2024) supports <EM>wgetscr</EM><STRONG>_</STRONG><EM>reg</EM>. It also + implements <EM>getscr</EM><STRONG>_</STRONG><EM>reg</EM>, operating on <EM>stdscr</EM>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>, <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> +ncurses 6.6 2025-02-15 <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -164,6 +165,7 @@ ncurses 6.5 2024-03-16 <STRONG><A HREF=" <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> diff --git a/doc/html/man/curs_outopts.3x.html b/doc/html/man/curs_outopts.3x.html index 7f04d92eabef..22d68265749a 100644 --- a/doc/html/man/curs_outopts.3x.html +++ b/doc/html/man/curs_outopts.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,120 +27,117 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_outopts.3x,v 1.64 2024/04/20 21:24:19 tom Exp @ + * @Id: curs_outopts.3x,v 1.106 2025/11/12 00:52:57 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_outopts 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_outopts 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_outopts 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_outopts 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>clearok</STRONG>, <STRONG>idlok</STRONG>, <STRONG>idcok</STRONG>, <STRONG>immedok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>setscrreg</STRONG>, <STRONG>wsetscrreg</STRONG>, - <STRONG>scrollok</STRONG> - set <EM>curses</EM> output options + <STRONG>clearok</STRONG>, <STRONG>idcok</STRONG>, <STRONG>idlok</STRONG>, <STRONG>immedok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>scrollok</STRONG>, <STRONG>setscrreg</STRONG>, + <STRONG>wsetscrreg</STRONG> - set <EM>curses</EM> output options </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>clearok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>idlok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>idcok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>immedok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>leaveok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>scrollok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>clearok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>idcok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>idlok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>immedok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>leaveok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>scrollok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>setscrreg(int</STRONG> <EM>top</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bot</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wsetscrreg(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>top</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bot</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wsetscrreg(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>top</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bot</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These routines set options that change the style of output within - <STRONG>curses</STRONG>. All options are initially <STRONG>FALSE</STRONG>, unless otherwise stated. It - is not necessary to turn these options off before calling <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG>. + These functions configure properties of <EM>curses</EM> windows that affect + their manner of output. Boolean-valued properties are initially <STRONG>FALSE</STRONG> + except where noted. <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> resets any terminal modes corresponding + to these properties; an application need not restore their initial + values. </PRE><H3><a name="h3-clearok">clearok</a></H3><PRE> - If <STRONG>clearok</STRONG> is called with <STRONG>TRUE</STRONG> as argument, the next call to <STRONG>wrefresh</STRONG> - with this window will clear the screen completely and redraw the entire - screen from scratch. This is useful when the contents of the screen - are uncertain, or in some cases for a more pleasing visual effect. If - the <EM>win</EM> argument to <STRONG>clearok</STRONG> is the global variable <STRONG>curscr</STRONG>, the next - call to <STRONG>wrefresh</STRONG> with any window causes the screen to be cleared and - repainted from scratch. + Setting <EM>win</EM>'s <STRONG>clearok</STRONG> property to <STRONG>TRUE</STRONG> causes the next <STRONG>wrefresh</STRONG> call on + it to clear the terminal screen and redraw it entirely. This property + is useful to restore the contents of the screen (perhaps because + another process has written to the terminal), or in some cases to + achieve a more pleasing visual effect. If <EM>win</EM> is <STRONG>curscr</STRONG> (see + <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>), the next <STRONG>wrefresh</STRONG> call on <EM>any</EM> window causes the + terminal screen to clear and redraw as above. <STRONG>wrefresh</STRONG> resets this + property to <STRONG>FALSE</STRONG>. -</PRE><H3><a name="h3-idlok">idlok</a></H3><PRE> - If <STRONG>idlok</STRONG> is called with <STRONG>TRUE</STRONG> as second argument, <STRONG>curses</STRONG> considers using - the hardware insert/delete line feature of terminals so equipped. - Calling <STRONG>idlok</STRONG> with <STRONG>FALSE</STRONG> as second argument disables use of line - insertion and deletion. This option should be enabled only if the - application needs insert/delete line, for example, for a screen editor. - It is disabled by default because insert/delete line tends to be - visually annoying when used in applications where it is not really - needed. If insert/delete line cannot be used, <STRONG>curses</STRONG> redraws the - changed portions of all lines. +</PRE><H3><a name="h3-idcok">idcok</a></H3><PRE> + (This property defaults <STRONG>TRUE</STRONG>.) Setting <EM>win</EM>'s <STRONG>idcok</STRONG> property to <STRONG>FALSE</STRONG> + prevents <EM>curses</EM> from using the insert/delete character capabilities of + terminal types possessing them according to the <EM>terminfo</EM> database. -</PRE><H3><a name="h3-idcok">idcok</a></H3><PRE> - If <STRONG>idcok</STRONG> is called with <STRONG>FALSE</STRONG> as second argument, <STRONG>curses</STRONG> no longer - considers using the hardware insert/delete character feature of - terminals so equipped. Use of character insert/delete is enabled by - default. Calling <STRONG>idcok</STRONG> with <STRONG>TRUE</STRONG> as second argument re-enables use of - character insertion and deletion. +</PRE><H3><a name="h3-idlok">idlok</a></H3><PRE> + Setting <EM>win</EM>'s <STRONG>idlok</STRONG> property to <STRONG>TRUE</STRONG> causes <EM>curses</EM> to consider using + the insert/delete line capabilities of terminal types possessing them + according to the <EM>terminfo</EM> database. Enable this option if the + application explicitly requires these operations, as a full-screen text + editor might; otherwise the results may be visually annoying to the + user. </PRE><H3><a name="h3-immedok">immedok</a></H3><PRE> - If <STRONG>immedok</STRONG> is called with <STRONG>TRUE</STRONG> as second argument, any change in the - window image, such as the ones caused by <STRONG>waddch,</STRONG> <STRONG>wclrtobot,</STRONG> <STRONG>wscrl</STRONG>, - etc., automatically causes a call to <STRONG>wrefresh</STRONG>. However, it may degrade - performance considerably, due to repeated calls to <STRONG>wrefresh</STRONG>. Calling - <STRONG>immedok</STRONG> with <STRONG>FALSE</STRONG> as second argument restores the default behavior, - i.e., deferring screen updates until a refresh is needed. + If <STRONG>immedok</STRONG> is called with <STRONG>TRUE</STRONG> as second argument, changes to the + window image, such as those caused by <STRONG>waddch</STRONG>, <STRONG>wclrtobot</STRONG>, or <STRONG>wscrl</STRONG>, + automatically cause a call to <STRONG>wrefresh</STRONG>. Setting a window's <STRONG>immedok</STRONG> + property may degrade performance considerably if writes are frequent. + Calling <STRONG>immedok</STRONG> with <STRONG>FALSE</STRONG> as second argument restores the default + behavior, deferring screen updates until a refresh is needed or + explicitly directed by the application. </PRE><H3><a name="h3-leaveok">leaveok</a></H3><PRE> - Normally, the hardware cursor is left at the location of the window - cursor being refreshed. The <STRONG>leaveok</STRONG> option allows the cursor to be - left wherever the update happens to leave it. It is useful for - applications where the cursor is not used, since it reduces the need - for cursor motions. + Normally, <EM>curses</EM> leaves the hardware cursor at the library's cursor + location of the window being refreshed. The <STRONG>leaveok</STRONG> option allows the + cursor to be left wherever the update happens to leave it. It is + useful for applications that do not employ a visible cursor, since it + reduces the need for cursor motions. </PRE><H3><a name="h3-scrollok">scrollok</a></H3><PRE> - The <STRONG>scrollok</STRONG> option controls what happens when the cursor of a window - is moved off the edge of the window or scrolling region, either as a - result of a newline action on the bottom line, or typing the last - character of the last line. If disabled, (<EM>bf</EM> is <STRONG>FALSE</STRONG>), the cursor is - left on the bottom line. If enabled, (<EM>bf</EM> is <STRONG>TRUE</STRONG>), the window is - scrolled up one line (Note that to get the physical scrolling effect on - the terminal, it is also necessary to call <STRONG>idlok</STRONG>). + The <STRONG>scrollok</STRONG> option controls what happens when a window's cursor moves + off the edge of the window or scrolling region, as a result of either + (1) writing a newline anywhere on its bottom line, or (2) writing a + character that advances the cursor to the last position on its bottom + line. If disabled (<EM>bf</EM> is <STRONG>FALSE</STRONG>), <EM>curses</EM> leaves the cursor on the + bottom line of the window. If enabled (<EM>bf</EM> is <STRONG>TRUE</STRONG>), <EM>curses</EM> scrolls the + window up one line. (To get the physical scrolling effect on the + terminal, the application must also enable <STRONG>idlok</STRONG>). </PRE><H3><a name="h3-setscrreg_wsetscrreg">setscrreg, wsetscrreg</a></H3><PRE> - The <STRONG>setscrreg</STRONG> and <STRONG>wsetscrreg</STRONG> routines allow the application programmer - to set a software scrolling region in a window. The <EM>top</EM> and <EM>bot</EM> - parameters are the line numbers of the top and bottom margin of the - scrolling region. (Line 0 is the top line of the window.) If this - option and <STRONG>scrollok</STRONG> are enabled, an attempt to move off the bottom - margin line causes all lines in the scrolling region to scroll one line - in the direction of the first line. Only the text of the window is - scrolled. (Note that this has nothing to do with the use of a physical - scrolling region capability in the terminal, like that in the VT100. - If <STRONG>idlok</STRONG> is enabled and the terminal has either a scrolling region or - insert/delete line capability, they will probably be used by the output - routines.) + The <STRONG>wsetscrreg</STRONG> and <STRONG>setscrreg</STRONG> functions allow the application to set a + software scrolling region in the specified window or <STRONG>stdscr</STRONG>, + respectively. The <EM>top</EM> and <EM>bot</EM> parameters are the line numbers of the + top and bottom margin of the scrolling region. If this option and + <STRONG>scrollok</STRONG> are enabled, an attempt to move off the bottom margin line + causes all lines in the scrolling region to scroll one line in the + direction of the first line. Only the text of the window is scrolled. + (This process has nothing to do with the scrolling region capability of + the terminal, as found in the DEC VT100.) If <STRONG>idlok</STRONG> is enabled and the + terminal has either a scrolling region or insert/delete line + capability, they will probably be used by the output routines. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> @@ -148,55 +145,72 @@ upon failure. All other routines that return an integer always return <STRONG>OK</STRONG>. - X/Open Curses does not specify any error conditions. + In <EM>ncurses</EM>, these functions fail if - In this implementation, + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, - <STRONG>o</STRONG> those functions that have a window pointer will return an error if - the window pointer is null + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, or - <STRONG>o</STRONG> <STRONG>wsetscrreg</STRONG> returns an error if the scrolling region limits extend - outside the window boundaries. + <STRONG>o</STRONG> (for <STRONG>setscrreg</STRONG> and <STRONG>wsetscrreg</STRONG>) the function is passed arguments + describing a scrolling region with limits that extend outside the + window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that <STRONG>clearok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>scrollok</STRONG>, <STRONG>idcok</STRONG>, and <STRONG>setscrreg</STRONG> may be + <STRONG>clearok</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>scrollok</STRONG>, <STRONG>idcok</STRONG>, and <STRONG>setscrreg</STRONG> may be implemented as macros. - The <STRONG>immedok</STRONG> routine is useful for windows that are used as terminal - emulators. + Unlike the other functions described by this page, <STRONG>setscrreg</STRONG> does not + accept a pointer-to-<EM>WINDOW</EM> parameter, but operates on <STRONG>stdscr</STRONG>. Use + <STRONG>wsetscrreg</STRONG> to configure the scrolling region of a selected window. + + Historically, applications used <STRONG>idcok(FALSE)</STRONG> to accommodate the "magic + cookie" feature of some terminal types; see subsection "Highlighting, + Underlining, and Visible Bells" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. When updating a line, + the presence of character cells with magic cookies in them made the + <EM>curses</EM> library's computations of characters to be rewritten inaccurate. + A better solution is to indicate the <STRONG>magic_cookie_glitch</STRONG> (<STRONG>xmc</STRONG>) + capability in the terminal's type description. + + <STRONG>immedok</STRONG> is useful for windows that are used as terminal emulators. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - Some historic curses implementations had, as an undocumented feature, - the ability to do the equivalent of <STRONG>clearok(...,</STRONG> <STRONG>1)</STRONG> by saying - <STRONG>touchwin(stdscr)</STRONG> or <STRONG>clear(stdscr)</STRONG>. This will not work under <EM>ncurses</EM>. + Some historic <EM>curses</EM> implementations, as an undocumented feature, did + the equivalent of "<STRONG>clearok(</STRONG>...<STRONG>,</STRONG> <STRONG>1)</STRONG>" when <STRONG>touchwin(stdstr)</STRONG> or + <STRONG>clear(stdstr)</STRONG> were used. This trick does not work with <EM>ncurses</EM>. - Earlier System V curses implementations specified that with <STRONG>scrollok</STRONG> - enabled, any window modification triggering a scroll also forced a - physical refresh. X/Open Curses does not require this, and <EM>ncurses</EM> - avoids doing it to perform better vertical-motion optimization at - <STRONG>wrefresh</STRONG> time. + Early System V <EM>curses</EM> implementations specified that with <EM>scrollok</EM> + enabled, any window modification triggering a scroll also forced a + physical refresh. X/Open Curses does not require this, and <EM>ncurses</EM> + avoids doing so to better optimize vertical motions upon a <EM>wrefresh</EM>. X/Open Curses does not mention that the cursor should be made invisible - as a side-effect of <STRONG>leaveok</STRONG>. SVr4 curses documentation does this, but - the code does not. Use <STRONG>curs_set</STRONG> to make the cursor invisible. + as a side effect of <EM>leaveok</EM>. SVr4 <EM>curses</EM> documentation notes this + behavior, but the code neglects to implement it. Use <STRONG><A HREF="curs_kernel.3x.html">curs_set(3x)</A></STRONG> to + make the cursor invisible. </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - <EM>ncurses</EM> formerly treated <STRONG><A HREF="curs_inopts.3x.html">nl(3x)</A></STRONG> and <STRONG><A HREF="curs_inopts.3x.html">nonl(3x)</A></STRONG> as both input <EM>and</EM> output - options, but no longer; see <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>. + 4BSD (1980) introduced <EM>clearok</EM>, <EM>leaveok</EM>, and <EM>scrollok</EM>. + + SVr2 (1984) supplied <EM>idlok</EM>, <EM>setscrreg</EM>, and <EM>wsetscrreg</EM>. + + SVr3.1 (1987) implemented <EM>idcok</EM> and <EM>immedok</EM>. + + <EM>ncurses</EM> formerly treated <EM>nl</EM> and <EM>nonl</EM> as both input <EM>and</EM> output options, + but no longer; see <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_clear.3x.html">curs_clear(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -205,8 +219,8 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="c <li><a href="#h2-DESCRIPTION">DESCRIPTION</a> <ul> <li><a href="#h3-clearok">clearok</a></li> -<li><a href="#h3-idlok">idlok</a></li> <li><a href="#h3-idcok">idcok</a></li> +<li><a href="#h3-idlok">idlok</a></li> <li><a href="#h3-immedok">immedok</a></li> <li><a href="#h3-leaveok">leaveok</a></li> <li><a href="#h3-scrollok">scrollok</a></li> diff --git a/doc/html/man/curs_overlay.3x.html b/doc/html/man/curs_overlay.3x.html index 61c4c1999fd1..5b431a4c69c5 100644 --- a/doc/html/man/curs_overlay.3x.html +++ b/doc/html/man/curs_overlay.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2020-2023,2024 Thomas E. Dickey * + * Copyright 2020-2024,2025 Thomas E. Dickey * * Copyright 1998-2013,2015 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_overlay.3x,v 1.43 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_overlay.3x,v 1.55 2025/01/19 00:51:10 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_overlay 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_overlay 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_overlay 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_overlay 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>overlay</STRONG>, <STRONG>overwrite</STRONG>, <STRONG>copywin</STRONG> - overlay <EM>curses</EM> windows and manipulate them @@ -66,47 +64,48 @@ </PRE><H3><a name="h3-overlay_overwrite">overlay, overwrite</a></H3><PRE> The <STRONG>overlay</STRONG> and <STRONG>overwrite</STRONG> routines overlay <EM>srcwin</EM> on top of <EM>dstwin</EM>. <EM>scrwin</EM> and <EM>dstwin</EM> are not required to be the same size; only text where - the two windows overlap is copied. The difference is that <STRONG>overlay</STRONG> is - non-destructive (blanks are not copied) whereas <STRONG>overwrite</STRONG> is + the two windows overlap is copied. The difference is that <STRONG>overlay</STRONG> is + non-destructive (blanks are not copied) whereas <STRONG>overwrite</STRONG> is destructive. </PRE><H3><a name="h3-copywin">copywin</a></H3><PRE> - The <STRONG>copywin</STRONG> routine provides a finer granularity of control over the + The <STRONG>copywin</STRONG> routine provides a finer granularity of control over the <STRONG>overlay</STRONG> and <STRONG>overwrite</STRONG> routines. As in the <STRONG>prefresh</STRONG> routine, a - rectangle is specified in the destination window, (<EM>dminrow</EM>, <EM>dmincol</EM>) - and (<EM>dmaxrow</EM>, <EM>dmaxcol</EM>), and the upper-left-corner coordinates of the - source window, (<EM>sminrow</EM>, <EM>smincol</EM>). If the argument <EM>overlay</EM> is <STRONG>true</STRONG>, + rectangle is specified in the destination window, (<EM>dminrow</EM>, <EM>dmincol</EM>) + and (<EM>dmaxrow</EM>, <EM>dmaxcol</EM>), and the upper-left-corner coordinates of the + source window, (<EM>sminrow</EM>, <EM>smincol</EM>). If the argument <EM>overlay</EM> is <STRONG>true</STRONG>, then copying is non-destructive, as in <STRONG>overlay</STRONG>. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - These routines return the integer <STRONG>ERR</STRONG> upon failure and an <STRONG>OK</STRONG> (SVr4 - specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful - completion. + These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. + + In <EM>ncurses</EM>, they return <STRONG>ERR</STRONG> if + + <STRONG>o</STRONG> either of the window pointers are null, or - X/Open defines no error conditions. In this implementation, <STRONG>copywin</STRONG>, - <STRONG>overlay</STRONG> and <STRONG>overwrite</STRONG> return an error if either of the window pointers - are null, or if some part of the window would be placed off-screen. + <STRONG>o</STRONG> any part of the window would be placed off-screen. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that <STRONG>overlay</STRONG> and <STRONG>overwrite</STRONG> may be macros. + <STRONG>overlay</STRONG> and <STRONG>overwrite</STRONG> may be implemented as macros. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are described in X/Open Curses, Issue 4, which adds - <EM>const</EM> qualifiers to the arguments. It further specifies their behavior - in the presence of characters with multibyte renditions (not yet - supported in this implementation). + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. It adds <EM>const</EM> qualifiers to the arguments. It + further specifies their behavior in the presence of characters with + multibyte renditions (not yet supported in this implementation). + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="curs_overlay.3x.html">curs_overlay(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_pad.3x.html b/doc/html/man/curs_pad.3x.html index ae27590967bc..b1ed17940f81 100644 --- a/doc/html/man/curs_pad.3x.html +++ b/doc/html/man/curs_pad.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_pad.3x,v 1.61 2024/04/27 17:55:43 tom Exp @ + * @Id: curs_pad.3x,v 1.81 2025/08/23 22:50:00 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_pad 3x 2024-04-27 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_pad 3x 2025-08-23 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_pad 3x 2024-04-27 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_pad 3x 2025-08-23 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>newpad</STRONG>, <STRONG>subpad</STRONG>, <STRONG>prefresh</STRONG>, <STRONG>pnoutrefresh</STRONG>, <STRONG>pechochar</STRONG>, <STRONG>pecho_wchar</STRONG> - create and display <EM>curses</EM> pads @@ -68,25 +66,25 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - A <EM>curses</EM> <EM>pad</EM> is like a window, except that it is not restricted by the - screen size, and is not necessarily associated with a particular part - of the screen. Pads can be used when a large window is needed, only + A <EM>curses</EM> <EM>pad</EM> is like a window, except that it is not restricted by the + screen size, and is not necessarily associated with a particular part + of the screen. Pads can be used when a large window is needed, only part of which is to be visible on the screen. Pads are not automatically refreshed by scrolling or input-echoing operations. - Pads cannot be refreshed with <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>; use <STRONG>prefresh</STRONG> or + Pads cannot be refreshed with <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>; use <STRONG>prefresh</STRONG> or <STRONG>pnoutrefresh</STRONG> instead. </PRE><H3><a name="h3-newpad">newpad</a></H3><PRE> - <STRONG>newpad</STRONG> creates and returns a pointer to a new pad data structure with + <STRONG>newpad</STRONG> creates and returns a pointer to a new pad data structure with the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>. </PRE><H3><a name="h3-subpad">subpad</a></H3><PRE> - <STRONG>subpad</STRONG> creates and returns a pointer to a subwindow within a pad with + <STRONG>subpad</STRONG> creates and returns a pointer to a subwindow within a pad with the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>. Unlike - <STRONG><A HREF="subwin.3x.html">subwin(3x)</A></STRONG>, which uses screen coordinates, the new pad is placed at + <STRONG><A HREF="subwin.3x.html">subwin(3x)</A></STRONG>, which uses screen coordinates, the new pad is placed at position (<EM>begin</EM><STRONG>_</STRONG><EM>y</EM>, <EM>begin</EM><STRONG>_</STRONG><EM>x</EM>) relative to its parent. Thus, changes made to one pad can affect both. When operating on a subpad, it is often necessary to call <STRONG><A HREF="curs_touch.3x.html">touchwin(3x)</A></STRONG> or <STRONG><A HREF="curs_touch.3x.html">touchline(3x)</A></STRONG> on <EM>parent</EM> before @@ -99,10 +97,10 @@ They require additional parameters are needed to indicate what portions of the pad and screen are involved. - <STRONG>o</STRONG> <EM>pminrow</EM> and <EM>pmincol</EM> specify the upper left-hand corner of a + <STRONG>o</STRONG> <EM>pminrow</EM> and <EM>pmincol</EM> specify the upper left-hand corner of a rectangular view of the pad. - <STRONG>o</STRONG> <EM>sminrow</EM>, <EM>smincol</EM>, <EM>smaxrow</EM>, and <EM>smaxcol</EM> specify the vertices of the + <STRONG>o</STRONG> <EM>sminrow</EM>, <EM>smincol</EM>, <EM>smaxrow</EM>, and <EM>smaxcol</EM> specify the vertices of the rectangle to be displayed on the screen. The lower right-hand corner of the rectangle to be displayed in the pad @@ -122,115 +120,123 @@ </PRE><H3><a name="h3-pecho_wchar">pecho_wchar</a></H3><PRE> <STRONG>pecho_wchar</STRONG> is functionally equivalent to calling <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> followed - by <STRONG>prefresh</STRONG>. It suggests to the <EM>curses</EM> optimizer that only a single - wide character is being output; a considerable performance benefit may - be thus enjoyed. The location of the character <EM>wch</EM> written to the pad + by <STRONG>prefresh</STRONG>. It suggests to the <EM>curses</EM> optimizer that only a single + wide character is being output; a considerable performance benefit may + be thus enjoyed. The location of the character <EM>wch</EM> written to the pad is used to populate the arguments to <STRONG>prefresh</STRONG>. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Functions that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 - specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful - completion. + Functions that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon + successful completion. - Functions that return pointers return <STRONG>NULL</STRONG> on error, and set <STRONG>errno</STRONG> to - <STRONG>ENOMEM</STRONG>. + Functions that return pointers return a null pointer on failure, and + set <EM>errno</EM> to <STRONG>ENOMEM</STRONG>. - X/Open Curses does not specify any error conditions. In this - implementation + In this implementation <STRONG>prefresh</STRONG> and <STRONG>pnoutrefresh</STRONG> - return an error if the window pointer is null, or if the window - is not really a pad or if the area to refresh extends off- - screen or if the minimum coordinates are greater than the - maximum. + return <STRONG>ERR</STRONG> if the window pointer is null, or if the window is + not really a pad or if the area to refresh extends off-screen + or if the minimum coordinates are greater than the maximum. <STRONG>pechochar</STRONG> - returns an error if the window is not really a pad, and the - associated call to <STRONG>wechochar</STRONG> returns an error. + returns <STRONG>ERR</STRONG> if the window is not really a pad, and the + associated call to <STRONG>wechochar</STRONG> returns <STRONG>ERR</STRONG>. <STRONG>pecho_wchar</STRONG> - returns an error if the window is not really a pad, and the - associated call to <STRONG>wecho_wchar</STRONG> returns an error. + returns <STRONG>ERR</STRONG> if the window is not really a pad, and the + associated call to <STRONG>wecho_wchar</STRONG> returns <STRONG>ERR</STRONG>. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - <STRONG>pechochar</STRONG> may be a macro. + <STRONG>pechochar</STRONG> may be implemented as a macro. + <EM>curses</EM> documentation is traditionally averse to motivating the term + "pad". The Apollo Aegis workstation operating system (<EM>circa</EM> 1981) + supported a graphical pad feature. -</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - BSD <EM>curses</EM> has no <EM>pad</EM> feature. + <STRONG>o</STRONG> These graphical pads could be much larger than the computer's + display. - SVr2 <EM>curses</EM> (1986) provided the <STRONG>newpad</STRONG> and related functions, - documenting them in a single line each. SVr3 (1987) provided more - extensive documentation. + <STRONG>o</STRONG> The read-only output from a command could be scrolled back to + inspect and select text from the pad. - The documentation does not explain the term <EM>pad</EM>. However, the Apollo - <EM>Aegis</EM> workstation operating system supported a graphical <EM>pad</EM> feature: + The two uses may be related. - <STRONG>o</STRONG> These graphical pads could be much larger than the computer's - display. - <STRONG>o</STRONG> The read-only output from a command could be scrolled back to - inspect, and select text from the pad. +</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - The two uses may be related. + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". - X/Open Curses, Issue 4 describes these functions, without significant - change from the SVr3 documentation. It describes no error conditions. - The behavior of <STRONG>subpad</STRONG> if the parent window is not a pad is - undocumented, and is not checked by the vendor Unix implementations: + The behavior of <EM>subpad</EM> if the parent window is not a pad is + undocumented, and is not checked by the vendor Unix implementations. - <STRONG>o</STRONG> SVr4 <EM>curses</EM> sets a flag in the <EM>WINDOW</EM> structure in <STRONG>newpad</STRONG> which - tells if the window is a <EM>pad</EM>. + <STRONG>o</STRONG> SVr4 <EM>curses</EM>'s <EM>newpad</EM> sets a flag in the <EM>WINDOW</EM> structure indicating + that the window is a pad. - However, it uses this information only in <STRONG>waddch</STRONG> (to decide if it - should call <STRONG>wrefresh</STRONG>) and <STRONG>wscrl</STRONG> (to avoid scrolling a pad), and - does not check in <STRONG>wrefresh</STRONG> to ensure that the pad is refreshed - properly. + However, it uses this information only in <EM>waddch</EM> (to decide if it + should call <EM>wrefresh</EM>) and <EM>wscrl</EM> (to avoid scrolling a pad); its + <EM>wrefresh</EM> does not check it to ensure that a pad is properly + updated. - <STRONG>o</STRONG> Solaris <EM>xcurses</EM> checks whether a window is a pad in <STRONG>wnoutrefresh</STRONG>, - returning <STRONG>ERR</STRONG> in that case. + <STRONG>o</STRONG> Solaris <EM>xcurses</EM> checks whether a window is a pad in its + <EM>wnoutrefresh</EM>, returning <EM>ERR</EM> in that case. - However, it only sets the flag for subwindows if the parent window - is a pad. Its <STRONG>newpad</STRONG> function does not set this information. - Consequently, the check will never fail. + However, it sets the flag on subwindows only if the parent window + is a pad. Its <EM>newpad</EM> does not set this information. Consequently, + the check never fails. - It makes no comparable check in <STRONG>pnoutrefresh</STRONG>, though interestingly - enough, a comment in the source code states that the lack of a - check was an MKS extension. + It makes no comparable check in <EM>pnoutrefresh</EM> -- though + interestingly enough, a comment in the source code states that the + lack of a check was an MKS extension. - <STRONG>o</STRONG> NetBSD 7 <EM>curses</EM> sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG> and - <STRONG>subpad</STRONG>, using this to help with the distinction between - <STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>. + <STRONG>o</STRONG> NetBSD 7 <EM>curses</EM> sets a flag in the <EM>WINDOW</EM> structure for <EM>newpad</EM> and + <EM>subpad</EM>, aiding itself to distinguish between <EM>wnoutrefresh</EM> and + <EM>pnoutrefresh</EM>. It does not check for the case where a subwindow is created in a - pad using <STRONG>subwin</STRONG> or <STRONG>derwin</STRONG>. + pad using <EM>subwin</EM> or <EM>derwin</EM>. - The <STRONG>dupwin</STRONG> function returns a regular window when duplicating a - pad. Likewise, <STRONG>getwin</STRONG> always returns a window, even if the saved + Its <EM>dupwin</EM> returns a regular window when duplicating a pad. + Likewise, its <EM>getwin</EM> always returns a window, even if the saved data was from a pad. - This implementation + <EM>ncurses</EM>: - <STRONG>o</STRONG> sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG> and <STRONG>subpad</STRONG>, + <STRONG>o</STRONG> sets a flag in the <EM>WINDOW</EM> structure for <EM>newpad</EM> and <EM>subpad</EM>, - <STRONG>o</STRONG> allows a <STRONG>subwin</STRONG> or <STRONG>derwin</STRONG> call to succeed having a pad parent by + <STRONG>o</STRONG> allows a <EM>subwin</EM> or <EM>derwin</EM> call to succeed having a pad parent by forcing the subwindow to be a pad, - <STRONG>o</STRONG> checks in both <STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG> to ensure that pads + <STRONG>o</STRONG> checks in both <EM>wnoutrefresh</EM> and <EM>pnoutrefresh</EM> to ensure that pads and windows are handled distinctly, and - <STRONG>o</STRONG> ensures that <STRONG>dupwin</STRONG> and <STRONG>getwin</STRONG> treat pads versus windows + <STRONG>o</STRONG> ensures that <EM>dupwin</EM> and <EM>getwin</EM> treat pads versus windows consistently. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG> +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr2 (1984) introduced <EM>newpad</EM>, <EM>prefresh</EM>, and <EM>pnoutrefresh</EM>, documenting + them in a single line each. + + SVr3 (1987) added <EM>subpad</EM> and <EM>pechochar</EM>, and provided more extensive + documentation. + The System V Interface Definition, Version 4 (1995), specified a + function named <EM>pechowchar</EM>. This was a later addition to SVr4.<EM>x</EM>, not + appearing in the first SVr4 (1989). It differs from X/Open's later + <EM>pecho</EM><STRONG>_</STRONG><EM>wchar</EM> in that its <EM>wstr</EM> parameter was a <EM>chtype</EM> instead of a + <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>, and was not <EM>const</EM>-qualified. -ncurses 6.5 2024-04-27 <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG> + +ncurses 6.6 2025-08-23 <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -248,6 +254,7 @@ ncurses 6.5 2024-04-27 <STRONG><A HRE <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_print.3x.html b/doc/html/man/curs_print.3x.html index 92fb48d47856..74177ac7c8ad 100644 --- a/doc/html/man/curs_print.3x.html +++ b/doc/html/man/curs_print.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_print.3x,v 1.38 2024/03/16 15:35:01 tom Exp @ + * @Id: curs_print.3x,v 1.41 2025/02/15 18:42:34 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_print 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_print 3x 2025-02-15 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_print 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_print 3x 2025-02-15 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>mcprint</STRONG> - write binary data to printer using <EM>terminfo</EM> capabilities @@ -53,57 +51,63 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>mcprint(char</STRONG> <STRONG>*</STRONG><EM>data</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>len</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mcprint(char</STRONG> <STRONG>*</STRONG> <EM>data</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>len</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - This function uses the <STRONG>mc5p</STRONG> or <STRONG>mc4</STRONG> and <STRONG>mc5</STRONG> capabilities, if they are - present, to ship given data to a printer attached to the terminal. + <STRONG>mcprint</STRONG>, an <EM>ncurses</EM> extension to the <EM>curses</EM> library, uses the + terminal's <STRONG>prtr_non</STRONG> (<STRONG>mc5p</STRONG>) or <STRONG>prtr_on</STRONG> (<STRONG>mc5</STRONG>) and <STRONG>prtr_off</STRONG> (<STRONG>mc4</STRONG>) media + copy capabilities, if defined, to send <EM>len</EM> bytes of the given string + <EM>data</EM> to a printer attached to the terminal. - Note that the <STRONG>mcprint</STRONG> code has no way to do flow control with the - printer or to know how much buffering it has. Your application is - responsible for keeping the rate of writes to the printer below its - continuous throughput rate (typically about half of its nominal cps - rating). Dot-matrix printers and 6-page-per-minute lasers can - typically handle 80cps, so a good conservative rule of thumb is to - sleep for a second after shipping each 80-character line. + <STRONG>mcprint</STRONG> has no means of flow control to the printer nor of knowing how + much buffering it has. Your application is responsible for keeping the + rate of writes to the printer below its continuous throughput rate, + typically about half of its nominal characters-per-second (cps) rating. + Dot-matrix printers and 6-page-per-minute laser printers can typically + handle 80 cps, so a conservative rule of thumb is to sleep for one + second after sending an 80-character line. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The <STRONG>mcprint</STRONG> function returns <STRONG>ERR</STRONG> if the write operation aborted for - some reason. In this case, <STRONG>errno</STRONG> will contain either an error - associated with <STRONG>write(2)</STRONG> or one of the following: + On success, <STRONG>mcprint</STRONG> returns the number of characters sent to the + printer. + + <STRONG>mcprint</STRONG> returns <STRONG>ERR</STRONG> if the write operation fails for any reason. In + that event, <STRONG>errno</STRONG> contains either a value set by <STRONG>write(2)</STRONG>, or one of + the following. <STRONG>ENODEV</STRONG> - Capabilities for printer redirection do not exist. + The terminal lacks relevant media copy capabilities. <STRONG>ENOMEM</STRONG> - Couldn't allocate sufficient memory to buffer the printer write. - - When <STRONG>mcprint</STRONG> succeeds, it returns the number of characters actually - sent to the printer. + <EM>ncurses</EM> could not allocate sufficient memory to buffer the write + operation. </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - <STRONG>mcprint</STRONG> was designed for <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>, and was not found in SVr4 <EM>curses</EM>, - 4.4BSD <EM>curses</EM>, or any other previous curses implementation. + <STRONG>mcprint</STRONG> is an <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> extension, and is not found in SVr4 <EM>curses</EM>, + 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> implementation. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - Applications employing this <EM>ncurses</EM> extension should condition its use + Applications employing this <EM>ncurses</EM> extension should condition its use on the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + <EM>ncurses</EM> introduced <EM>mcprint</EM> prior to version 1.9.9g (1996). + + </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE> - Padding in the <STRONG>mc5p</STRONG>, <STRONG>mc4</STRONG>, and <STRONG>mc5</STRONG> capabilities is not interpreted. + Padding in the <STRONG>prtr_non</STRONG> (<STRONG>mc5p</STRONG>), <STRONG>prtr_on</STRONG> (<STRONG>mc5</STRONG>), and <STRONG>prtr_off</STRONG> (<STRONG>mc4</STRONG>) + capabilities is not interpreted. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> +ncurses 6.6 2025-02-15 <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -113,6 +117,7 @@ ncurses 6.5 2024-03-16 <STRONG><A HREF= <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-BUGS">BUGS</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> diff --git a/doc/html/man/curs_printw.3x.html b/doc/html/man/curs_printw.3x.html index 259b56121b93..c4a3743ff696 100644 --- a/doc/html/man/curs_printw.3x.html +++ b/doc/html/man/curs_printw.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_printw.3x,v 1.53 2024/04/20 19:18:18 tom Exp @ + * @Id: curs_printw.3x,v 1.65 2025/08/16 19:59:33 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_printw 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_printw 3x 2025-08-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_printw 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_printw 3x 2025-08-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>printw</STRONG>, <STRONG>wprintw</STRONG>, <STRONG>mvprintw</STRONG>, <STRONG>mvwprintw</STRONG>, <STRONG>vwprintw</STRONG>, <STRONG>vw_printw</STRONG> - write formatted output to a <EM>curses</EM> window @@ -80,74 +78,75 @@ These functions return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success. In <EM>ncurses</EM>, failure occurs if the library cannot allocate enough memory - for the buffer into which the output is formatted, or if the window + for the buffer into which the output is formatted, or if the window pointer <EM>win</EM> is null. - Functions prefixed with "mv" first perform cursor movement and fail if + Functions prefixed with "mv" first perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - No wide character counterpart functions are defined by the "wide" + No wide character counterpart functions are defined by the "wide" <EM>ncurses</EM> configuration nor by any standard. To format and write a wide- character string to a <EM>curses</EM> window, consider using <STRONG>swprintf(3)</STRONG> and <STRONG><A HREF="curs_addwstr.3x.html">waddwstr(3x)</A></STRONG> or similar. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. It specifies no - error conditions for them. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - <EM>ncurses</EM> defines <STRONG>vw_printw</STRONG> and <STRONG>vwprintw</STRONG> identically to support legacy + <EM>ncurses</EM> defines <STRONG>vw_printw</STRONG> and <STRONG>vwprintw</STRONG> identically to support legacy applications. However, the latter is obsolete. - <STRONG>o</STRONG> X/Open Curses, Issue 4 Version 2 (1996), marked <STRONG>vwprintw</STRONG> as - requiring <EM>varargs.h</EM> and "TO BE WITHDRAWN", and specified <STRONG>vw_printw</STRONG> + <STRONG>o</STRONG> X/Open Curses Issue 4 Version 2 (1996), marked <STRONG>vwprintw</STRONG> as + requiring <EM>varargs.h</EM> and "TO BE WITHDRAWN", and specified <STRONG>vw_printw</STRONG> using the <EM>stdarg.h</EM> interface. - <STRONG>o</STRONG> X/Open Curses, Issue 5, Draft 2 (December 2007) marked <STRONG>vwprintw</STRONG> + <STRONG>o</STRONG> X/Open Curses Issue 5, Draft 2 (December 2007) marked <STRONG>vwprintw</STRONG> (along with <STRONG>vwscanw</STRONG> and the <EM>termcap</EM> interface) as withdrawn. After - incorporating review comments, this became X/Open Curses, Issue 7 + incorporating review comments, this became X/Open Curses Issue 7 (2009). <STRONG>o</STRONG> <EM>ncurses</EM> provides <STRONG>vwprintw</STRONG>, but marks it as deprecated. </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - While <STRONG>printw</STRONG> was implemented in 4BSD (November 1980), it was unused - until 4.2BSD (August 1983), which employed it for games. That early - version of <EM>curses</EM> preceded the ANSI C standard of 1989. It did not use - <EM>varargs.h</EM>, though that had been available since Seventh Edition Unix - (1979). In 1991 (a couple of years after SVr4 was generally available, - and after the C standard was published), other developers updated the - library, using <EM>stdarg.h</EM> internally in 4.4BSD <EM>curses</EM>. Even with this - improvement, BSD <EM>curses</EM> did not use function prototypes (nor even - declare functions) in <EM>curses.h</EM> until 1992. - - SVr2 (1984) documented <STRONG>printw</STRONG> and <STRONG>wprintw</STRONG> tersely as "printf on <STRONG>stdscr</STRONG>" - and "printf on <EM>win</EM>", respectively. - - SVr3 (1987) added <STRONG>mvprintw</STRONG> and <STRONG>mvwprintw</STRONG>, with a three-line summary - asserting that they were analogous to <STRONG>printf(3)</STRONG>, explaining that the - string that <STRONG>printf(3)</STRONG> would write to the standard output stream would - instead be output using <STRONG>waddstr</STRONG> to the given window. SVr3 also - implemented <STRONG>vwprintw</STRONG>, describing its third parameter as a <EM>va</EM><STRONG>_</STRONG><EM>list</EM>, - defined in <EM>varargs.h</EM>, and referred the reader to the manual pages for + 4BSD (1980) introduced <EM>wprintw</EM> and its variants. It implemented all as + functions, not macros; this initial distribution of <EM>curses</EM> preceded the + ANSI C standard of 1989, prior to which a variadic macro facility was + not widely available in the language. <EM>printw</EM> went unused in Berkeley + distributions until 4.1cBSD (1983), which employed it in games. 4BSD's + <EM>wprintw</EM> did not use <EM>varargs.h</EM>, which had been available since Seventh + Edition Unix (1979). In 1991 (a couple of years after SVr4 was + generally available, and after the C standard was published), other + developers updated the library, using <EM>stdarg.h</EM> internally in 4.4BSD + <EM>curses</EM>. Even with this improvement, BSD <EM>curses</EM> did not use function + prototypes (nor even declare functions) in <EM>curses.h</EM> until 1992. + + 4BSD documented <EM>printw</EM> and <EM>wprintw</EM> tersely as "printf on <EM>stdscr</EM>" and + "printf on <EM>win</EM>", respectively. + + SVr3 summarized the functions in three lines, asserting that they were + analogous to <STRONG>printf(3)</STRONG> and explaining that the string that <STRONG>printf(3)</STRONG> + would write to the standard output stream would instead be output using + <EM>waddstr</EM> to the given window. + + SVr3 added <EM>vwprintw</EM>, describing its third parameter as a <EM>va</EM><STRONG>_</STRONG><EM>list</EM>, + defined in <EM>varargs.h</EM>, and referred the reader to the manual pages for <EM>varargs</EM> and <EM>vprintf</EM> for detailed descriptions. - SVr4 (1989) introduced no new variations of <EM>printw</EM>, but provided for + SVr4 (1989) introduced no new variations of <EM>printw</EM>, but provided for using either <EM>varargs.h</EM> or <EM>stdarg.h</EM> to define the <EM>va</EM><STRONG>_</STRONG><EM>list</EM> type. - X/Open Curses, Issue 4 (1995), defined <STRONG>vw_printw</STRONG> to replace <STRONG>vwprintw</STRONG>, + X/Open Curses Issue 4 (1995), defined <EM>vw</EM><STRONG>_</STRONG><EM>printw</EM> to replace <EM>vwprintw</EM>, stating that its <EM>va</EM><STRONG>_</STRONG><EM>list</EM> type is defined in <EM>stdarg.h</EM>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG>, <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG>, <STRONG>printf(3)</STRONG>, <STRONG>vprintf(3)</STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG> +ncurses 6.6 2025-08-16 <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_refresh.3x.html b/doc/html/man/curs_refresh.3x.html index 4beec325ad44..87d3ab311dbc 100644 --- a/doc/html/man/curs_refresh.3x.html +++ b/doc/html/man/curs_refresh.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2016 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_refresh.3x,v 1.46 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_refresh.3x,v 1.58 2025/01/19 00:51:10 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_refresh 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_refresh 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_refresh 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_refresh 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>doupdate</STRONG>, <STRONG>redrawwin</STRONG>, <STRONG>refresh</STRONG>, <STRONG>wnoutrefresh</STRONG>, <STRONG>wredrawln</STRONG>, <STRONG>wrefresh</STRONG> - refresh <EM>curses</EM> windows or lines thereupon @@ -96,19 +94,19 @@ <EM>physical</EM> <EM>screen</EM> and does the actual update. If the programmer wishes to output several windows at once, a series of - calls to <STRONG>wrefresh</STRONG> results in alternating calls to <STRONG>wnoutrefresh</STRONG> and - <STRONG>doupdate</STRONG>, causing several bursts of output to the screen. By first - calling <STRONG>wnoutrefresh</STRONG> for each window, it is then possible to call - <STRONG>doupdate</STRONG> once, resulting in only one burst of output, with fewer total + calls to <STRONG>wrefresh</STRONG> results in alternating calls to <STRONG>wnoutrefresh</STRONG> and + <STRONG>doupdate</STRONG>, causing several bursts of output to the screen. By first + calling <STRONG>wnoutrefresh</STRONG> for each window, it is then possible to call + <STRONG>doupdate</STRONG> once, resulting in only one burst of output, with fewer total characters transmitted and less CPU time used. - If the <EM>win</EM> argument to <STRONG>wrefresh</STRONG> is the <EM>physical</EM> <EM>screen</EM> (i.e., the - global variable <STRONG>curscr</STRONG>), the screen is immediately cleared and + If the <EM>win</EM> argument to <STRONG>wrefresh</STRONG> is the <EM>physical</EM> <EM>screen</EM> (i.e., the + global variable <STRONG>curscr</STRONG>), the screen is immediately cleared and repainted from scratch. - The phrase "copies the named window to the virtual screen" above is - ambiguous. What actually happens is that all <EM>touched</EM> (changed) lines - in the window are copied to the virtual screen. This affects programs + The phrase "copies the named window to the virtual screen" above is + ambiguous. What actually happens is that all <EM>touched</EM> (changed) lines + in the window are copied to the virtual screen. This affects programs that use overlapping windows; it means that if two windows overlap, you can refresh them in either order and the overlap region will be modified only when it is explicitly changed. (But see the section on @@ -123,44 +121,42 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - These routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 - specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful - completion. + These routines return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> - X/Open Curses does not specify any error conditions. In this - implementation + In this implementation <STRONG>wnoutrefresh</STRONG> - returns an error if the window pointer is null, or if the - window is really a pad. + returns <STRONG>ERR</STRONG> if the window pointer is null, or if the window is + really a pad. <STRONG>wredrawln</STRONG> - returns an error if the associated call to <STRONG>touchln</STRONG> returns an - error. + return <STRONG>ERR</STRONG> if the associated call to <STRONG>touchln</STRONG> returns <STRONG>ERR</STRONG>. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that <STRONG>refresh</STRONG> and <STRONG>redrawwin</STRONG> may be macros. + <STRONG>refresh</STRONG> and <STRONG>redrawwin</STRONG> may be implemented as macros. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". - Whether <STRONG>wnoutrefresh</STRONG> copies to the virtual screen the entire contents + Whether <STRONG>wnoutrefresh</STRONG> copies to the virtual screen the entire contents of a window or just its changed portions has never been well-documented in historic curses versions (including SVr4). It might be unwise to rely on either behavior in programs that might have to be linked with other curses implementations. Instead, you can do an explicit <STRONG>touchwin</STRONG> - before the <STRONG>wnoutrefresh</STRONG> call to guarantee an entire-contents copy + before the <STRONG>wnoutrefresh</STRONG> call to guarantee an entire-contents copy anywhere. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_scanw.3x.html b/doc/html/man/curs_scanw.3x.html index d0b9b7947d47..6e7f697a327c 100644 --- a/doc/html/man/curs_scanw.3x.html +++ b/doc/html/man/curs_scanw.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_scanw.3x,v 1.53 2024/04/20 19:18:18 tom Exp @ + * @Id: curs_scanw.3x,v 1.62 2025/07/05 13:03:05 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_scanw 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_scanw 3x 2025-07-05 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_scanw 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_scanw 3x 2025-07-05 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>scanw</STRONG>, <STRONG>wscanw</STRONG>, <STRONG>mvscanw</STRONG>, <STRONG>mvwscanw</STRONG>, <STRONG>vwscanw</STRONG>, <STRONG>vw_scanw</STRONG> - read formatted input from a <EM>curses</EM> window @@ -100,19 +98,19 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. It specifies no - error conditions for them. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - <EM>ncurses</EM> defines <STRONG>vw_scanw</STRONG> and <STRONG>vwscanw</STRONG> identically to support legacy + <EM>ncurses</EM> defines <STRONG>vw_scanw</STRONG> and <STRONG>vwscanw</STRONG> identically to support legacy applications. However, the latter is obsolete. - <STRONG>o</STRONG> X/Open Curses, Issue 4 Version 2 (1996), marked <STRONG>vwscanw</STRONG> as - requiring <EM>varargs.h</EM> and "TO BE WITHDRAWN", and specified <STRONG>vw_scanw</STRONG> - using the <EM>stdarg.h</EM> interface. + <STRONG>o</STRONG> X/Open Curses Issue 4 Version 2 (1996), marked <STRONG>vwscanw</STRONG> as requiring + <EM>varargs.h</EM> and "TO BE WITHDRAWN", and specified <STRONG>vw_scanw</STRONG> using the + <EM>stdarg.h</EM> interface. - <STRONG>o</STRONG> X/Open Curses, Issue 5, Draft 2 (December 2007) marked <STRONG>vwscanw</STRONG> + <STRONG>o</STRONG> X/Open Curses Issue 5, Draft 2 (December 2007) marked <STRONG>vwscanw</STRONG> (along with <STRONG>vwscanw</STRONG> and the <EM>termcap</EM> interface) as withdrawn. After - incorporating review comments, this became X/Open Curses, Issue 7 + incorporating review comments, this became X/Open Curses Issue 7 (2009). <STRONG>o</STRONG> <EM>ncurses</EM> provides <STRONG>vwscanw</STRONG>, but marks it as deprecated. @@ -141,45 +139,42 @@ </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - <STRONG>scanw</STRONG> was implemented in 4BSD (November 1980); that early version of - <EM>curses</EM> preceded the ANSI C standard of 1989. The function was unused - in Berkeley distributions for over ten years, until 4.4BSD, which - employed it in a game. The 4BSD <STRONG>scanw</STRONG> did not use <EM>varargs.h</EM>, though - that had been available since Seventh Edition Unix (1979). In 1991 (a - couple of years after SVr4 was generally available, and after the C - standard was published), other developers updated the library, using - <EM>stdarg.h</EM> internally in 4.4BSD <EM>curses</EM>. Even with this improvement, BSD - <EM>curses</EM> did not use function prototypes (nor even declare functions) in - <EM>curses.h</EM> until 1992. - - SVr2 (1984) documented <STRONG>scanw</STRONG> and <STRONG>wscanw</STRONG> tersely as "scanf through - <STRONG>stdscr</STRONG>" and "scanf through <EM>win</EM>", respectively. - - SVr3 (1987) added <STRONG>mvscanw</STRONG>, and <STRONG>mvwscanw</STRONG>, stating - - "[t]hese routines correspond to <STRONG>scanf(3S)</STRONG>, as do their arguments - and return values. <STRONG>wgetstr</STRONG>() is called on the window, and the - resulting line is used as input for the scan." - - SVr3 also implemented <STRONG>vwscanw</STRONG>, describing its third parameter as a - <EM>va</EM><STRONG>_</STRONG><EM>list</EM>, defined in <EM>varargs.h</EM>, and referred the reader to the manual - pages for <EM>varargs</EM> and <EM>vprintf</EM> for detailed descriptions. (Because the - SVr3 documentation does not mention <EM>vscanf</EM>, the reference to <EM>vprintf</EM> - might not be an error). + 4BSD (1980) introduced <EM>wscanw</EM> and its variants. It implemented all as + functions, not macros; this initial distribution of <EM>curses</EM> preceded the + ANSI C standard of 1989, prior to which a variadic macro facility was + not widely available. <EM>scanw</EM> went unused in Berkeley distributions + until 4.3BSD-Reno (1990), which employed it in a game. 4BSD's <EM>wscanw</EM> + did not use <EM>varargs.h</EM>, which had been available since Seventh Edition + Unix (1979). In 1991 (a couple of years after SVr4 was generally + available, and after the C standard was published), other developers + updated the library, using <EM>stdarg.h</EM> internally in 4.4BSD <EM>curses</EM>. Even + with this improvement, BSD <EM>curses</EM> did not use function prototypes (nor + even declare functions) in <EM>curses.h</EM> until 1992. + + 4BSD documented <EM>scanw</EM> and <EM>wscanw</EM> tersely as "scanf through <EM>stdscr</EM>" and + "scanf through <EM>win</EM>", respectively. SVr3 (1987) stated + + [t]hese routines correspond to <STRONG>scanf(3S)</STRONG>, as do their arguments + and return values. <EM>wgetstr</EM>() is called on the window, and the + resulting line is used as input for the scan. + + SVr3 added <EM>vwscanw</EM>, describing its third parameter as a <EM>va</EM><STRONG>_</STRONG><EM>list</EM>, + defined in <EM>varargs.h</EM>, and referred the reader to the manual pages for + <EM>varargs</EM> and <EM>vprintf</EM> for detailed descriptions. (Because SVr3 + documentation does not mention <EM>vscanf</EM>, the reference to <EM>vprintf</EM> might + not be an error). SVr4 (1989) introduced no new variations of <EM>scanw</EM>, but provided for using either <EM>varargs.h</EM> or <EM>stdarg.h</EM> to define the <EM>va</EM><STRONG>_</STRONG><EM>list</EM> type. - X/Open Curses, Issue 4 (1995), defined <EM>vw</EM><STRONG>_</STRONG><EM>scanw</EM> to replace <EM>vwscanw</EM>, + X/Open Curses Issue 4 (1995) defined <EM>vw</EM><STRONG>_</STRONG><EM>scanw</EM> to replace <EM>vwscanw</EM>, stating that its <EM>va</EM><STRONG>_</STRONG><EM>list</EM> type is defined in <EM>stdarg.h</EM>. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG>, <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG>, <STRONG>scanf(3)</STRONG>, <STRONG>vscanf(3)</STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG> +ncurses 6.6 2025-07-05 <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_scr_dump.3x.html b/doc/html/man/curs_scr_dump.3x.html index f1759cb3b700..ec58e75cfe60 100644 --- a/doc/html/man/curs_scr_dump.3x.html +++ b/doc/html/man/curs_scr_dump.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_scr_dump.3x,v 1.43 2024/04/20 18:54:36 tom Exp @ + * @Id: curs_scr_dump.3x,v 1.55 2025/01/19 00:51:10 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_scr_dump 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_scr_dump 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_scr_dump 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_scr_dump 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>scr_dump</STRONG>, <STRONG>scr_restore</STRONG>, <STRONG>scr_init</STRONG>, <STRONG>scr_set</STRONG> - read/write a <EM>curses</EM> screen from/to a file @@ -54,10 +52,10 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>scr_dump(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>filename</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>scr_restore(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>filename</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>scr_init(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>filename</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>scr_set(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>filename</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>scr_dump(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>filename</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>scr_restore(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>filename</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>scr_init(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>filename</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>scr_set(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>filename</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> @@ -73,65 +71,93 @@ </PRE><H3><a name="h3-scr_restore">scr_restore</a></H3><PRE> - <STRONG>scr_restore</STRONG> updates the virtual screen to contain the contents of - <EM>filename</EM> (if it was validly written with <STRONG>scr_dump</STRONG>). No refresh is - performed; after performing any further desired updates, call - <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> or similar. + <STRONG>scr_restore</STRONG> updates the virtual screen to match the contents of + <EM>filename</EM> (if validly written with <STRONG>scr_dump</STRONG>). <EM>curses</EM> does not perform a + refresh; after making any desired changes, call <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> or + similar. </PRE><H3><a name="h3-scr_init">scr_init</a></H3><PRE> - <STRONG>scr_init</STRONG> reads <EM>filename</EM>, using it to initialize <EM>curses</EM> data structures - describing the state of the terminal screen. If these data are valid, - <EM>curses</EM> bases its next update of the screen on this information rather - than clearing it and starting from scratch. + <STRONG>scr_init</STRONG> reads <EM>filename</EM>, using it to initialize <EM>curses</EM> data structures + describing the state of the terminal screen. <EM>curses</EM> then, if it + decides the terminal state is valid, bases its next update of the + screen on this information rather than clearing it and starting from + scratch. - The data fail the validity check + <EM>curses</EM> regards the terminal as in an invalid state for computation of + updates based on the contents of <EM>filename</EM> if - <STRONG>o</STRONG> if the terminal employs <EM>terminfo</EM> capabilities <STRONG>exit_ca_mode</STRONG> (<STRONG>rmcup</STRONG>) - or <STRONG>non_rev_rmcup</STRONG> (<STRONG>nrrmc</STRONG>) are defined, or + <STRONG>o</STRONG> <EM>curses</EM> knows that the terminal has been written to since the + preceding <STRONG>scr_dump</STRONG> call, or - <STRONG>o</STRONG> if <EM>curses</EM> knows that the terminal has been written to since the - preceding <STRONG>scr_dump</STRONG> call. + <STRONG>o</STRONG> the terminal type supports the <EM>terminfo</EM> capabilities <STRONG>exit_ca_mode</STRONG> + (<STRONG>rmcup</STRONG>) or <STRONG>non_rev_rmcup</STRONG> (<STRONG>nrrmc</STRONG>). - <STRONG>scr_init</STRONG> could be used after <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG>system(3)</STRONG> to share the - screen with another process that has done a <STRONG>scr_dump</STRONG> after <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG>. + Either of the foregoing conditions means that <EM>curses</EM> cannot assume that + the terminal's contents match their representation in <EM>filename</EM>. The + former is due to terminal features (such as <STRONG>xterm(1)</STRONG>'s "alternate + screen") that couple cursor-positioning mode with a local cache of + screen contents. <EM>curses</EM> cannot know whether the terminal is displaying + from that local cache at the time the application calls <STRONG>scr_init</STRONG>, so it + makes a pessimistic assumption that a full redraw is required; see + subsection "Cursor Motions" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. + + <STRONG>scr_init</STRONG> could be used after <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG>system(3)</STRONG> to share the + screen with another process that has done a <STRONG>scr_dump</STRONG> after <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG>. + An application that supports suspending its state on exit and + subsequent resumption upon later execution might use <STRONG>scr_dump</STRONG> and + <STRONG>scr_init</STRONG> thus. </PRE><H3><a name="h3-scr_set">scr_set</a></H3><PRE> - The <STRONG>scr_set</STRONG> routine is a combination of <STRONG>scr_restore</STRONG> and <STRONG>scr_init</STRONG>. It - tells the program that the information in <EM>filename</EM> is what is currently - on the screen, and also what the program wants on the screen. This can - be thought of as a screen inheritance function. + <STRONG>scr_set</STRONG> combines <STRONG>scr_restore</STRONG> and <STRONG>scr_init</STRONG>, synchronizing the contents + of <EM>filename</EM> with the virtual screen. It can be regarded as a screen + inheritance function; consider a real-time screen-sharing application. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> These functions return <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. - X/Open defines no failure conditions. In this implementation, each - function fails if it cannot open <EM>filename</EM>. + In <EM>ncurses</EM>, each function returns <STRONG>ERR</STRONG> if it cannot open <EM>filename</EM>. + <STRONG>scr_init</STRONG>, <STRONG>scr_restore</STRONG>, and <STRONG>scr_set</STRONG> return <STRONG>ERR</STRONG> if the contents of + <EM>filename</EM> are invalid. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - <STRONG>scr_init</STRONG>, <STRONG>scr_set</STRONG>, and <STRONG>scr_restore</STRONG> may be macros. + <STRONG>scr_init</STRONG>, <STRONG>scr_restore</STRONG>, and <STRONG>scr_set</STRONG> may be implemented as macros. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. SVr4 omitted the <EM>const</EM> qualifiers. - SVr4 documentation describes <STRONG>scr_init</STRONG> such that the dump data is also + SVr4 documentation describes <EM>scr</EM><STRONG>_</STRONG><EM>init</EM> such that the dump data is also considered invalid "if the time-stamp of the tty is old" but does not define "old". + As of 2024, <EM>PDCurses</EM> provides these functions. NetBSD <EM>curses</EM> does not. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, - <STRONG>system(3)</STRONG>, <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG> + Other implementations of <EM>curses</EM> store the window in binary form, which + makes the dump dependent upon the <EM>curses</EM> library's internal data + structures. <EM>ncurses</EM> avoids this drawback by storing the dump in + textual form, allowing more flexible use of the data. For instance, + the <EM>scr</EM><STRONG>_</STRONG><EM>restore</EM> of SVr4 <EM>curses</EM> requires that the dumped window have the + same dimensions as the restored window. <EM>ncurses</EM> uses its <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> + extension to adjust the restored window size. +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr3 (1987) introduced <EM>scr</EM><STRONG>_</STRONG><EM>dump</EM>, <EM>scr</EM><STRONG>_</STRONG><EM>init</EM>, and <EM>scr</EM><STRONG>_</STRONG><EM>restore</EM>. SVr3.1 + added <EM>scr</EM><STRONG>_</STRONG><EM>set</EM>. + + +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, + <STRONG>system(3)</STRONG>, <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -148,6 +174,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="cu <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_scroll.3x.html b/doc/html/man/curs_scroll.3x.html index 5b827feded69..3e0e44ad48a6 100644 --- a/doc/html/man/curs_scroll.3x.html +++ b/doc/html/man/curs_scroll.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2006,2010 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_scroll.3x,v 1.43 2024/04/20 18:54:36 tom Exp @ + * @Id: curs_scroll.3x,v 1.59 2025/04/05 22:20:39 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_scroll 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_scroll 3x 2025-04-05 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_scroll 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_scroll 3x 2025-04-05 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>scroll</STRONG>, <STRONG>scrl</STRONG>, <STRONG>wscrl</STRONG> - scroll a <EM>curses</EM> window @@ -53,27 +51,28 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>scroll(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>scroll(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>scrl(int</STRONG> <EM>n</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>wscrl(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wscrl(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>n</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> <STRONG>scroll</STRONG> scrolls the given window up one line. That is, every visible - line we might number <EM>i</EM> becomes line <EM>i</EM>-1. The text of the top line in - the window disappears and the bottom line is populated with blank - characters; see <STRONG><A HREF="curs_bkgd.3x.html">bkgd(3x)</A></STRONG> or <STRONG><A HREF="curs_bkgrnd.3x.html">bkgrnd(3x)</A></STRONG>. As an optimization, if the - scrolling region of the window is the entire screen, the physical - screen may be scrolled at the same time; see <STRONG><A HREF="curs_variables.3x.html">curscr(3x)</A></STRONG>. - - <STRONG>scrl</STRONG> and <STRONG>wscrl</STRONG> scroll <STRONG>stdscr</STRONG> or the specified window up or down - depending on the sign of <EM>n</EM>. + line we might number <EM>i</EM> becomes line <EM>i</EM>-1. <STRONG>wscrl</STRONG> and <STRONG>scrl</STRONG> scroll the + specified window or <STRONG>stdscr</STRONG>, respectively, up or down per the sign of <EM>n</EM>. <STRONG>o</STRONG> For positive <EM>n</EM>, line <EM>i</EM>+<EM>n</EM> becomes <EM>i</EM> (scrolling up); <STRONG>o</STRONG> for negative <EM>n</EM>, line <EM>i</EM>-<EM>n</EM> becomes <EM>i</EM> (scrolling down). + A line that scrolls beyond the window boundaries disappears; <EM>curses</EM> + populates a new one emerging at the opposite boundary with the + background character; see <STRONG><A HREF="curs_bkgd.3x.html">bkgd(3x)</A></STRONG> (wide-character API users: + <STRONG><A HREF="curs_bkgrnd.3x.html">bkgrnd(3x)</A></STRONG>). As an optimization, if the scrolling region of the window + is the entire screen, the physical screen may be scrolled at the same + time; see <STRONG><A HREF="curs_variables.3x.html">curscr(3x)</A></STRONG>. + The cursor does not move. These functions perform no operation unless scrolling is enabled for the window via <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>. @@ -81,41 +80,52 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> These functions return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon success. - <EM>ncurses</EM> returns <STRONG>ERR</STRONG> if scrolling is not enabled in the window, for - example with <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>, or if the <EM>WINDOW</EM> pointer is null. + In <EM>ncurses</EM>, they return <STRONG>ERR</STRONG> if + + <STRONG>o</STRONG> the <EM>curses</EM> screen has not been initialized, + + <STRONG>o</STRONG> (for functions taking a <EM>WINDOW</EM> pointer argument) <EM>win</EM> is a null + pointer, or + + <STRONG>o</STRONG> scrolling is not enabled in the window (as by <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>). </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> + <STRONG>scroll</STRONG> and <STRONG>scrl</STRONG> may be implemented as macros. + Unusually, there is no <STRONG>wscroll</STRONG> function; <STRONG>scroll</STRONG> behaves as one would expect <STRONG>wscroll</STRONG> to, accepting a <EM>WINDOW</EM> pointer argument. - <STRONG>scrl</STRONG> and <STRONG>scroll</STRONG> may be implemented as macros. - </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. It defines no error - conditions. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>" as a successful - return value. + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". - SVr4 indicates that the optimization of physically scrolling - immediately if the scroll region is the entire screen "is" performed, - not "may be" performed. <EM>ncurses</EM> deliberately does not guarantee that - this will occur, to leave open the possibility of smarter optimization - of multiple scroll actions on the next update. + SVr4 indicates that the optimization of physically scrolling + immediately if the scroll region is the entire screen "is" performed, + not "may be" performed. <EM>ncurses</EM> deliberately does not guarantee that + this occurs, to leave open the possibility of better optimization of + multiple scroll actions on the next update. - Neither SVr4 <EM>curses</EM> nor X/Open Curses specify whether the current - attribute or current color pair of blanks generated by the scroll - function are zeroed. <EM>ncurses</EM> does so. + Neither SVr4 <EM>curses</EM> nor X/Open Curses specify whether these functions + zero the attributes or color pair identifier of the background + character. In <EM>ncurses</EM>, they do not. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced <EM>scroll</EM>, defining it as a function. + SVr3.1 (1987) added <EM>scrl</EM> and <EM>wscrl</EM>, redefining <EM>scroll</EM> as a macro + wrapping the latter. -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG> +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> + +ncurses 6.6 2025-04-05 <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -125,6 +135,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF=" <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_slk.3x.html b/doc/html/man/curs_slk.3x.html index 52f8c29fbdef..2e050b9f139e 100644 --- a/doc/html/man/curs_slk.3x.html +++ b/doc/html/man/curs_slk.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_slk.3x,v 1.71 2024/04/20 18:54:36 tom Exp @ + * @Id: curs_slk.3x,v 1.85 2025/01/19 00:51:10 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_slk 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_slk 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_slk 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_slk 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>slk_init</STRONG>, <STRONG>slk_set</STRONG>, <STRONG>slk_wset</STRONG>, <STRONG>slk_refresh</STRONG>, <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_label</STRONG>, <STRONG>slk_clear</STRONG>, <STRONG>slk_restore</STRONG>, <STRONG>slk_touch</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, @@ -108,14 +106,14 @@ <STRONG>2</STRONG> indicates the PC-like 4-4-4 mode. - <STRONG>3</STRONG> is again the PC-like 4-4-4 mode, but in addition an index line is - generated, helping the user to associate each label with its - numbered function key. <STRONG>LINES</STRONG> and the vertical size of <STRONG>stdscr</STRONG> are + <STRONG>3</STRONG> is again the PC-like 4-4-4 mode, but in addition an index line is + generated, helping the user to associate each label with its + numbered function key. <STRONG>LINES</STRONG> and the vertical size of <STRONG>stdscr</STRONG> are further reduced. </PRE><H3><a name="h3-Labels">Labels</a></H3><PRE> - Populate the labels with normal strings (<STRONG>slk_set</STRONG>) or wide-character + Populate the labels with normal strings (<STRONG>slk_set</STRONG>) or wide-character strings (<STRONG>slk_wset</STRONG>). Each function takes three parameters. <EM>labnum</EM> is the label number, from <STRONG>1</STRONG> to <STRONG>8</STRONG> (12 if <EM>fmt</EM> in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or @@ -125,83 +123,79 @@ in <STRONG>slk_init</STRONG> is <STRONG>2</STRONG> or <STRONG>3</STRONG>) characters in length. A empty string or a null pointer sets up a blank label. - <EM>align</EM> is <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, aligning <EM>label</EM> to the left, center, or right, + <EM>align</EM> is <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>, aligning <EM>label</EM> to the left, center, or right, respectively, within the 8 (5) character cells housing it. - <STRONG>slk_label</STRONG> obtains the string assigned to label number <EM>labnum</EM>, with any + <STRONG>slk_label</STRONG> obtains the string assigned to label number <EM>labnum</EM>, with any leading and trailing blanks stripped. </PRE><H3><a name="h3-Screen-Updates">Screen Updates</a></H3><PRE> - <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> affect the soft key label lines as + <STRONG>slk_refresh</STRONG> and <STRONG>slk_noutrefresh</STRONG> affect the soft key label lines as <STRONG>wrefresh</STRONG> and <STRONG>wnoutrefresh</STRONG> do the <EM>curses</EM> window. The <STRONG>slk_clear</STRONG> routine clears the soft labels from the screen. - The <STRONG>slk_restore</STRONG> routine restores the soft labels to the screen after a + The <STRONG>slk_restore</STRONG> routine restores the soft labels to the screen after a <STRONG>slk_clear</STRONG> has been performed. - The <STRONG>slk_touch</STRONG> routine forces all the soft labels to be output the next + The <STRONG>slk_touch</STRONG> routine forces all the soft labels to be output the next time a <STRONG>slk_noutrefresh</STRONG> is performed. </PRE><H3><a name="h3-Video-Attributes">Video Attributes</a></H3><PRE> - The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attr</STRONG> routines - correspond to <STRONG>attron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>attroff</STRONG>, and <STRONG>attr_get</STRONG>, respectively. - They have an effect only if soft labels are simulated on the bottom - line of the screen. The default highlight for soft key labels is + The <STRONG>slk_attron</STRONG>, <STRONG>slk_attrset</STRONG>, <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attr</STRONG> routines + correspond to <STRONG>attron</STRONG>, <STRONG>attrset</STRONG>, <STRONG>attroff</STRONG>, and <STRONG>attr_get</STRONG>, respectively. + They have an effect only if soft labels are simulated on the bottom + line of the screen. The default highlight for soft key labels is <STRONG>A_STANDOUT</STRONG> (as in System V <EM>curses</EM>, which does not document this fact). </PRE><H3><a name="h3-Colors">Colors</a></H3><PRE> - The <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>. It has an effect only + The <STRONG>slk_color</STRONG> routine corresponds to <STRONG>color_set</STRONG>. It has an effect only if soft labels are simulated on the bottom line of the screen. - Because <STRONG>slk_color</STRONG> accepts only <EM>short</EM> (signed 16-bit integer) values, - this implementation provides <STRONG>extended_slk_color</STRONG>, which accepts an <EM>int</EM> + Because <STRONG>slk_color</STRONG> accepts only <EM>short</EM> (signed 16-bit integer) values, + this implementation provides <STRONG>extended_slk_color</STRONG>, which accepts an <EM>int</EM> value of at least 32 bits. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 - specifies only "an integer value other than <STRONG>ERR</STRONG>") upon successful - completion. - - X/Open Curses defines no error conditions. + Functions that return integers return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon + success. - In this implementation + In <EM>ncurses</EM>, <STRONG>slk_attr</STRONG> returns the attribute used for the soft keys. - <STRONG>slk_attroff</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_clear</STRONG>, <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_refresh</STRONG>, + <STRONG>slk_attroff</STRONG>, <STRONG>slk_attron</STRONG>, <STRONG>slk_clear</STRONG>, <STRONG>slk_noutrefresh</STRONG>, <STRONG>slk_refresh</STRONG>, <STRONG>slk_touch</STRONG> - return an error if the terminal or the softkeys were not + return <STRONG>ERR</STRONG> if the terminal or the softkeys were not initialized. <STRONG>slk_attrset</STRONG> - returns an error if the terminal or the softkeys were not + returns <STRONG>ERR</STRONG> if the terminal or the softkeys were not initialized. <STRONG>slk_attr_set</STRONG> - returns an error if the terminal or the softkeys were not - initialized, or the color pair is outside the range + returns <STRONG>ERR</STRONG> if the terminal or the softkeys were not + initialized, or the color pair is outside the range 0..<STRONG>COLOR_PAIRS</STRONG>-1. <STRONG>slk_color</STRONG> - returns an error if the terminal or the softkeys were not - initialized, or the color pair is outside the range + returns <STRONG>ERR</STRONG> if the terminal or the softkeys were not + initialized, or the color pair is outside the range 0..<STRONG>COLOR_PAIRS</STRONG>-1. <STRONG>slk_init</STRONG> - returns an error if the format parameter is outside the range - 0..3. + returns <STRONG>ERR</STRONG> if the format parameter is outside the range 0..3. <STRONG>slk_label</STRONG> - returns <STRONG>NULL</STRONG> on error. + returns <EM>NULL</EM> on error. <STRONG>slk_set</STRONG> - returns an error if the terminal or the softkeys were not + returns <STRONG>ERR</STRONG> if the terminal or the softkeys were not initialized, or the <EM>labnum</EM> parameter is outside the range of label counts, or if the format parameter is outside the range 0..2, or if memory for the labels cannot be allocated. @@ -214,9 +208,9 @@ </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> X/Open Curses documents the <EM>opts</EM> argument as reserved for future use, - saying that it must be null. This implementation uses that parameter - in ABI 6 for the functions which have a color pair parameter to support - extended color pairs. + saying that it must be a null pointer. The <EM>ncurses</EM> 6 ABI uses it for + the functions that accept a color pair parameter to support extended + color pairs. For functions which modify the color, e.g., <STRONG>slk_attr_set</STRONG>, if <EM>opts</EM> is set it is treated as a pointer to <EM>int</EM>, and used to set the color pair @@ -224,8 +218,11 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions, with some differences - from SVr4 <EM>curses</EM>: + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". <STRONG>o</STRONG> X/Open added functions like the SVr4 attribute-manipulation functions <STRONG>slk_attron</STRONG>, <STRONG>slk_attroff</STRONG>, and <STRONG>slk_attrset</STRONG>, but which use @@ -253,32 +250,32 @@ <STRONG>o</STRONG> Soft-key groups are an array of <EM>ng</EM> integers. - <STRONG>o</STRONG> In SVr4, <STRONG>slk_init</STRONG> calls <STRONG>slk_start</STRONG> passing a null for <EM>gp</EM>. For this - case, <STRONG>slk_start</STRONG> uses the number of groups <EM>ng</EM> (3 for the 3-2-3 + <STRONG>o</STRONG> In SVr4, <STRONG>slk_init</STRONG> calls <STRONG>slk_start</STRONG> passing a null for <EM>gp</EM>. For this + case, <STRONG>slk_start</STRONG> uses the number of groups <EM>ng</EM> (3 for the 3-2-3 layout, 2 for the 4-4 layout) which <STRONG>slk_init</STRONG> provided. - If <EM>ng</EM> is neither 2 or 3, <STRONG>slk_start</STRONG> checks the terminfo <STRONG>fln</STRONG> - (label_format) capability, interpreting that as a comma-separated + If <EM>ng</EM> is neither 2 or 3, <STRONG>slk_start</STRONG> checks the terminfo <STRONG>fln</STRONG> + (label_format) capability, interpreting that as a comma-separated list of numbers, e.g., "3,2,3" for the 3-2-3 layout. Finally, if there is no <STRONG>fln</STRONG> capability, <STRONG>slk_start</STRONG> returns <STRONG>ERR</STRONG>. - <STRONG>o</STRONG> If <STRONG>slk_start</STRONG> is given a non-null <EM>gp</EM>, it copies the <EM>ng</EM> elements of + <STRONG>o</STRONG> If <STRONG>slk_start</STRONG> is given a non-null <EM>gp</EM>, it copies the <EM>ng</EM> elements of the group of soft-keys, up to 16. - If there are more than 16 elements, <STRONG>slk_start</STRONG> returns an error. + If there are more than 16 elements, <STRONG>slk_start</STRONG> returns <STRONG>ERR</STRONG>. - <STRONG>o</STRONG> The format codes <STRONG>2</STRONG> and <STRONG>3</STRONG> for <STRONG>slk_init</STRONG> were added by <EM>ncurses</EM> in - 1996. PDCurses 2.4 added this feature in 2001. + <STRONG>o</STRONG> The format codes <STRONG>2</STRONG> and <STRONG>3</STRONG> for <STRONG>slk_init</STRONG> were added by <EM>ncurses</EM> in + 1996. <EM>PDCurses</EM> 2.4 added this feature in 2001. The function <STRONG>slk_attr</STRONG> was added by <EM>ncurses</EM> in 1996. - X/Open Curses does not specify a limit for the number of colors and + X/Open Curses does not specify a limit for the number of colors and color pairs which a terminal can support. However, in its use of <EM>short</EM> for the parameters, it carries over SVr4's implementation detail for the compiled terminfo database, which uses signed 16-bit numbers. This - implementation provides extended versions of those functions which use - <EM>int</EM> parameters, allowing applications to use larger color- and pair- + implementation provides extended versions of those functions which use + <EM>int</EM> parameters, allowing applications to use larger color- and pair- numbers. @@ -311,9 +308,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_sp_funcs.3x.html b/doc/html/man/curs_sp_funcs.3x.html index 7695f68c40e4..4f361e30bb88 100644 --- a/doc/html/man/curs_sp_funcs.3x.html +++ b/doc/html/man/curs_sp_funcs.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2010-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_sp_funcs.3x,v 1.50 2024/04/20 18:56:31 tom Exp @ + * @Id: curs_sp_funcs.3x,v 1.57 2025/02/01 22:47:44 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_sp_funcs 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_sp_funcs 3x 2025-02-01 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_sp_funcs 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_sp_funcs 3x 2025-02-01 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>curs_sp_funcs</STRONG> - <EM>curses</EM> screen-pointer extension @@ -53,169 +51,169 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>alloc_pair_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bg</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>assume_default_colors_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bg</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>baudrate_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>beep_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>bool</STRONG> <STRONG>can_change_color_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>cbreak_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>color_content_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>short*</STRONG> <EM>r</EM><STRONG>,</STRONG> <STRONG>short*</STRONG> <EM>g</EM><STRONG>,</STRONG> <STRONG>short*</STRONG> <EM>b</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>curs_set_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>visibility</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>def_prog_mode_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>def_shell_mode_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>define_key_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>definition</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>keycode</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>delay_output_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ms</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>doupdate_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>echo_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>endwin_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>char</STRONG> <STRONG>erasechar_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>erasewchar_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wc</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>alloc_pair_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bg</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>assume_default_colors_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bg</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>baudrate_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>beep_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>bool</STRONG> <STRONG>can_change_color_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>cbreak_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>color_content_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG> <EM>r</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG> <EM>g</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG> <EM>b</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>curs_set_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>visibility</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>def_prog_mode_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>def_shell_mode_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>define_key_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>definition</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>keycode</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>delay_output_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ms</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>doupdate_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>echo_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>endwin_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>erasechar_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>erasewchar_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wc</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>extended_color_content_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>r</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>g</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>b</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>extended_pair_content_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>bg</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>extended_slk_color_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pair</EM><STRONG>);</STRONG> - - <STRONG>void</STRONG> <STRONG>filter_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>find_pair_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bg</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>flash_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>flushinp_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>free_pair_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pair</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>get_escdelay_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>getmouse_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>MEVENT*</STRONG> <EM>event</EM><STRONG>);</STRONG> - <STRONG>WINDOW*</STRONG> <STRONG>getwin_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>FILE*</STRONG> <EM>filep</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>halfdelay_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>tenths</EM><STRONG>);</STRONG> - <STRONG>bool</STRONG> <STRONG>has_colors_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - - <STRONG>bool</STRONG> <STRONG>has_ic_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>bool</STRONG> <STRONG>has_il_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>has_key_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>c</EM><STRONG>);</STRONG> - <STRONG>bool</STRONG> <STRONG>has_mouse_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>init_color_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>r</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>g</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>b</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>init_extended_color_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>r</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>g</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>b</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>init_extended_pair_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bg</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>init_pair_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>bg</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>intrflush_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>WINDOW*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>is_cbreak_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>is_echo_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>is_nl_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>is_raw_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>bool</STRONG> <STRONG>is_term_resized_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>lines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>columns</EM><STRONG>);</STRONG> - <STRONG>bool</STRONG> <STRONG>isendwin_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>key_defined_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>definition</EM><STRONG>);</STRONG> - <STRONG>char*</STRONG> <STRONG>keybound_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>keycode</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>count</EM><STRONG>);</STRONG> - <STRONG>NCURSES_CONST</STRONG> <STRONG>char*</STRONG> <STRONG>keyname_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>c</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>keyok_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>keycode</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>enable</EM><STRONG>);</STRONG> - <STRONG>char</STRONG> <STRONG>killchar_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>killwchar_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wc</EM><STRONG>);</STRONG> - <STRONG>char*</STRONG> <STRONG>longname_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mcprint_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>data</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>len</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mouseinterval_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>erval</EM><STRONG>);</STRONG> - <STRONG>mmask_t</STRONG> <STRONG>mousemask_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>mmask_t</STRONG> <EM>newmask</EM><STRONG>,</STRONG> <STRONG>mmask_t</STRONG> <STRONG>*</STRONG><EM>oldmask</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvcur_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldcol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newcol</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>napms_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ms</EM><STRONG>);</STRONG> - <STRONG>WINDOW*</STRONG> <STRONG>newpad_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>nrows</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>);</STRONG> - <STRONG>SCREEN*</STRONG> <STRONG>new_prescr(void);</STRONG> - <STRONG>SCREEN*</STRONG> <STRONG>newterm_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>type</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG><EM>outfd</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG><EM>infd</EM><STRONG>);</STRONG> - - <STRONG>WINDOW*</STRONG> <STRONG>newwin_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>nl_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>nocbreak_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>noecho_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>nofilter_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>nonl_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>noqiflush_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>noraw_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>pair_content_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>short*</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>short*</STRONG> <EM>bg</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>qiflush_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>raw_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>reset_color_pairs_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>reset_prog_mode_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>reset_shell_mode_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>resetty_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>resize_term_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>lines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>columns</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>resizeterm_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>lines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>columns</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>ripoffline_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>line</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>init</EM><STRONG>)(WINDOW*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fmt</EM><STRONG>));</STRONG> - <STRONG>int</STRONG> <STRONG>savetty_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>scr_init_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>filename</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>scr_restore_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>filename</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>scr_set_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>filename</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>set_escdelay_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ms</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>set_tabsize_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>cols</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>slk_attrset_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>a</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>slk_attr_set_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void*</STRONG><EM>opts</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>slk_attroff_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>a</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>slk_attron_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>a</EM><STRONG>);</STRONG> - <STRONG>attr_t</STRONG> <STRONG>slk_attr_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>slk_clear_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>slk_color_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>slk_init_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fmt</EM><STRONG>);</STRONG> - <STRONG>char*</STRONG> <STRONG>slk_label_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>labnum</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>slk_noutrefresh_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>slk_refresh_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>slk_restore_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>slk_set_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>labnum</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>label</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fmt</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>slk_touch_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>start_color_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>attr_t</STRONG> <STRONG>term_attrs_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - - <STRONG>chtype</STRONG> <STRONG>termattrs_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>char*</STRONG> <STRONG>termname_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>typeahead_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fd</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>unget_wch_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <EM>wc</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>ungetch_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>c</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>ungetmouse_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>MEVENT*</STRONG> <EM>event</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>use_default_colors_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>use_env_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>use_legacy_coding_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>level</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>extended_pair_content_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>bg</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>extended_slk_color_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pair</EM><STRONG>);</STRONG> + + <STRONG>void</STRONG> <STRONG>filter_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>find_pair_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bg</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>flash_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>flushinp_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>free_pair_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pair</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>get_escdelay_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>getmouse_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>MEVENT</STRONG> <STRONG>*</STRONG> <EM>event</EM><STRONG>);</STRONG> + <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>getwin_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG> <EM>filep</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>halfdelay_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>tenths</EM><STRONG>);</STRONG> + <STRONG>bool</STRONG> <STRONG>has_colors_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + + <STRONG>bool</STRONG> <STRONG>has_ic_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>bool</STRONG> <STRONG>has_il_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>has_key_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>c</EM><STRONG>);</STRONG> + <STRONG>bool</STRONG> <STRONG>has_mouse_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>init_color_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>r</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>g</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>b</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>init_extended_color_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>color</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>r</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>g</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>b</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>init_extended_pair_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>bg</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>init_pair_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>bg</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>intrflush_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>is_cbreak_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>is_echo_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>is_nl_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>is_raw_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>bool</STRONG> <STRONG>is_term_resized_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>lines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>columns</EM><STRONG>);</STRONG> + <STRONG>bool</STRONG> <STRONG>isendwin_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>key_defined_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>definition</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>keybound_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>keycode</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>count</EM><STRONG>);</STRONG> + <STRONG>NCURSES_CONST</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>keyname_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>c</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>keyok_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>keycode</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>enable</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>killchar_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>killwchar_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>wchar_t</STRONG> <STRONG>*</STRONG><EM>wc</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>longname_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mcprint_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>data</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>len</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mouseinterval_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>erval</EM><STRONG>);</STRONG> + <STRONG>mmask_t</STRONG> <STRONG>mousemask_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>mmask_t</STRONG> <EM>newmask</EM><STRONG>,</STRONG> <STRONG>mmask_t</STRONG> <STRONG>*</STRONG><EM>oldmask</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvcur_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldcol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newcol</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>napms_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ms</EM><STRONG>);</STRONG> + <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>newpad_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>nrows</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>);</STRONG> + <STRONG>SCREEN</STRONG> <STRONG>*</STRONG> <STRONG>new_prescr(void);</STRONG> + <STRONG>SCREEN</STRONG> <STRONG>*</STRONG> <STRONG>newterm_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>type</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG><EM>outf</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG><EM>inf</EM><STRONG>);</STRONG> + + <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>newwin_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>nl_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>nocbreak_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>noecho_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>nofilter_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>nonl_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>noqiflush_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>noraw_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>pair_content_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG> <EM>fg</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <STRONG>*</STRONG> <EM>bg</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>qiflush_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>raw_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>reset_color_pairs_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>reset_prog_mode_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>reset_shell_mode_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>resetty_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>resize_term_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>lines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>columns</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>resizeterm_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>lines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>columns</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>ripoffline_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>line</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>init</EM><STRONG>)(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fmt</EM><STRONG>));</STRONG> + <STRONG>int</STRONG> <STRONG>savetty_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>scr_init_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>filename</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>scr_restore_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>filename</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>scr_set_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>filename</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>set_escdelay_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ms</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>set_tabsize_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>cols</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>slk_attrset_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>a</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>slk_attr_set_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>slk_attroff_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>a</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>slk_attron_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>chtype</STRONG> <EM>a</EM><STRONG>);</STRONG> + <STRONG>attr_t</STRONG> <STRONG>slk_attr_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>slk_clear_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>slk_color_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>slk_init_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fmt</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>slk_label_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>labnum</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>slk_noutrefresh_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>slk_refresh_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>slk_restore_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>slk_set_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>labnum</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>label</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fmt</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>slk_touch_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>start_color_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>attr_t</STRONG> <STRONG>term_attrs_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + + <STRONG>chtype</STRONG> <STRONG>termattrs_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>termname_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>typeahead_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>fd</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>unget_wch_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>wchar_t</STRONG> <EM>wc</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>ungetch_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>c</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>ungetmouse_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>MEVENT</STRONG> <STRONG>*</STRONG> <EM>event</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>use_default_colors_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>use_env_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>use_legacy_coding_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>level</EM><STRONG>);</STRONG> <STRONG>void</STRONG> <STRONG>use_tioctl_sp(SCREEN</STRONG> <STRONG>*</STRONG><EM>sp</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>vid_attr_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG> <EM>opts</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>vid_puts_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG> <EM>opts</EM><STRONG>,</STRONG> <STRONG>NCURSES_SP_OUTC</STRONG> <EM>putc</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>vidattr_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>vidputs_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>NCURSES_SP_OUTC</STRONG> <EM>putc</EM><STRONG>);</STRONG> - <STRONG>wchar_t*</STRONG> <STRONG>wunctrl_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>vid_attr_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG> <EM>opts</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>vid_puts_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG> <EM>opts</EM><STRONG>,</STRONG> <STRONG>NCURSES_SP_OUTC</STRONG> <EM>putc</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>vidattr_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>vidputs_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>NCURSES_SP_OUTC</STRONG> <EM>putc</EM><STRONG>);</STRONG> + <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <STRONG>wunctrl_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> <STRONG>#include</STRONG> <STRONG><form.h></STRONG> - <STRONG>FORM*</STRONG> <STRONG>new_form_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>FIELD</STRONG> <STRONG>**</STRONG><EM>fields</EM><STRONG>);</STRONG> + <STRONG>FORM</STRONG> <STRONG>*</STRONG> <STRONG>new_form_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>FIELD</STRONG> <STRONG>**</STRONG><EM>fields</EM><STRONG>);</STRONG> <STRONG>#include</STRONG> <STRONG><menu.h></STRONG> - <STRONG>MENU*</STRONG> <STRONG>new_menu_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>ITEM</STRONG> <STRONG>**</STRONG><EM>items</EM><STRONG>);</STRONG> + <STRONG>MENU</STRONG> <STRONG>*</STRONG> <STRONG>new_menu_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>ITEM</STRONG> <STRONG>**</STRONG><EM>items</EM><STRONG>);</STRONG> <STRONG>#include</STRONG> <STRONG><panel.h></STRONG> - <STRONG>PANEL*</STRONG> <STRONG>ceiling_panel(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>PANEL*</STRONG> <STRONG>ground_panel(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>update_panels_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>PANEL</STRONG> <STRONG>*</STRONG> <STRONG>ceiling_panel(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>PANEL</STRONG> <STRONG>*</STRONG> <STRONG>ground_panel(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>update_panels_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>);</STRONG> <STRONG>#include</STRONG> <STRONG><term.h></STRONG> - <STRONG>int</STRONG> <STRONG>del_curterm_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>putp_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>restartterm_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>NCURSES_CONST</STRONG> <STRONG>char*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG> - <STRONG>TERMINAL*</STRONG> <STRONG>set_curterm_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>TERMINAL*</STRONG><EM>nterm</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>tgetent_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>bp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>name</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>tgetflag_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>tgetnum_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG> - <STRONG>char*</STRONG> <STRONG>tgetstr_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>**</STRONG><EM>area</EM><STRONG>);</STRONG> - <STRONG>char*</STRONG> <STRONG>tgoto_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>col</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>row</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>tigetflag_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>tigetnum_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG> - <STRONG>char*</STRONG> <STRONG>tigetstr_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>del_curterm_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>putp_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>restartterm_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>NCURSES_CONST</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG> + <STRONG>TERMINAL</STRONG> <STRONG>*</STRONG> <STRONG>set_curterm_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>tgetent_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>bp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>name</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>tgetflag_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>tgetnum_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>tgetstr_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>**</STRONG><EM>area</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>tgoto_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>col</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>row</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>tigetflag_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG> + + <STRONG>int</STRONG> <STRONG>tigetnum_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>tigetstr_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>capname</EM><STRONG>);</STRONG> <EM>/*</EM> <EM>tparm</EM><STRONG>_</STRONG><EM>sp</EM> <EM>may</EM> <EM>use</EM> <EM>9</EM> <EM>long</EM> <EM>parameters</EM> <EM>rather</EM> <EM>than</EM> <EM>being</EM> <EM>variadic</EM> <EM>*/</EM> - <STRONG>char*</STRONG> <STRONG>tparm_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG> - <STRONG>int</STRONG> <STRONG>tputs_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>NCURSES_SP_OUTC</STRONG> <EM>putc</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>tparm_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG> + <STRONG>int</STRONG> <STRONG>tputs_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>NCURSES_SP_OUTC</STRONG> <EM>putc</EM><STRONG>);</STRONG> <STRONG>#include</STRONG> <STRONG><unctrl.h></STRONG> - <STRONG>NCURSES_CONST</STRONG> <STRONG>char*</STRONG> <STRONG>unctrl_sp(SCREEN*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> + <STRONG>NCURSES_CONST</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>unctrl_sp(SCREEN</STRONG> <STRONG>*</STRONG> <EM>sp</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> @@ -265,10 +263,10 @@ NCURSES_SP_NAME The new functions are named using the macro <EM>NCURSES</EM><STRONG>_</STRONG><EM>SP</EM><STRONG>_</STRONG><EM>NAME</EM>, which - hides the actual implementation. Currently this adds a "_sp" - suffix to the name of the unextended function. This manual page - indexes the extensions showing the full name. However the proper - usage of these functions uses the macro, to provide for the + hides the actual implementation. Currently this adds a "_sp" + suffix to the name of the unextended function. This manual page + indexes the extensions showing the full name. However the proper + usage of these functions uses the macro, to provide for the possibility of changing the naming convention for specific library configurations. @@ -292,9 +290,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>, <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> +ncurses 6.6 2025-02-01 <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_termattrs.3x.html b/doc/html/man/curs_termattrs.3x.html index 386b4b4b39a6..10677bd461de 100644 --- a/doc/html/man/curs_termattrs.3x.html +++ b/doc/html/man/curs_termattrs.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2015 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,29 +27,27 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_termattrs.3x,v 1.41 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_termattrs.3x,v 1.61 2025/08/23 22:39:20 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_termattrs 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_termattrs 3x 2025-08-23 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_termattrs 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_termattrs 3x 2025-08-23 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>baudrate</STRONG>, <STRONG>erasechar</STRONG>, <STRONG>erasewchar</STRONG>, <STRONG>has_ic</STRONG>, <STRONG>has_il</STRONG>, <STRONG>killchar</STRONG>, <STRONG>killwchar</STRONG>, - <STRONG>longname</STRONG>, <STRONG>term_attrs</STRONG>, <STRONG>termattrs</STRONG>, <STRONG>termname</STRONG> - <EM>curses</EM> environment query - routines + <STRONG>longname</STRONG>, <STRONG>term_attrs</STRONG>, <STRONG>termattrs</STRONG>, <STRONG>termname</STRONG> - get and set terminal + attributes with <EM>curses</EM> </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> @@ -57,99 +55,114 @@ <STRONG>int</STRONG> <STRONG>baudrate(void);</STRONG> <STRONG>char</STRONG> <STRONG>erasechar(void);</STRONG> - <STRONG>int</STRONG> <STRONG>erasewchar(wchar_t</STRONG> <STRONG>*</STRONG><EM>wc</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>erasewchar(wchar_t</STRONG> <STRONG>*</STRONG> <EM>wc</EM><STRONG>);</STRONG> <STRONG>bool</STRONG> <STRONG>has_ic(void);</STRONG> <STRONG>bool</STRONG> <STRONG>has_il(void);</STRONG> <STRONG>char</STRONG> <STRONG>killchar(void);</STRONG> - <STRONG>int</STRONG> <STRONG>killwchar(wchar_t</STRONG> <STRONG>*</STRONG><EM>wc</EM><STRONG>);</STRONG> - <STRONG>char</STRONG> <STRONG>*longname(void);</STRONG> + <STRONG>int</STRONG> <STRONG>killwchar(wchar_t</STRONG> <STRONG>*</STRONG> <EM>wc</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>longname(void);</STRONG> <STRONG>attr_t</STRONG> <STRONG>term_attrs(void);</STRONG> <STRONG>chtype</STRONG> <STRONG>termattrs(void);</STRONG> - <STRONG>char</STRONG> <STRONG>*termname(void);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>termname(void);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> </PRE><H3><a name="h3-baudrate">baudrate</a></H3><PRE> - The <STRONG>baudrate</STRONG> routine returns the output speed of the terminal. The - number returned is in bits per second, for example <STRONG>9600</STRONG>, and is an - integer. + <STRONG>baudrate</STRONG> returns the line speed of the terminal, an integer value + measured in bits per second, for example <STRONG>9600</STRONG>. </PRE><H3><a name="h3-erasechar_erasewchar">erasechar, erasewchar</a></H3><PRE> - The <STRONG>erasechar</STRONG> routine returns the user's current erase character. + <STRONG>erasechar</STRONG> returns the terminal's erase character. - The <STRONG>erasewchar</STRONG> routine stores the current erase character in the - location referenced by <EM>wc</EM>. If no erase character has been defined, the - routine fails and the location referenced by <EM>wc</EM> is not changed. + <STRONG>erasewchar</STRONG> stores the erase character in the location referenced by <EM>wc</EM>. + If no erase character has been defined, it fails and the location + referenced by <EM>wc</EM> is not changed. </PRE><H3><a name="h3-has_ic_has_il">has_ic, has_il</a></H3><PRE> - The <STRONG>has_ic</STRONG> routine is true if the terminal has insert- and delete- - character capabilities. + <STRONG>has_ic</STRONG> returns <STRONG>TRUE</STRONG> if the terminal has insert- and delete-character + capabilities. - The <STRONG>has_il</STRONG> routine is true if the terminal has insert- and delete-line - capabilities, or can simulate them using scrolling regions. This might - be used to determine if it would be appropriate to turn on physical - scrolling using <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG>. + <STRONG>has_il</STRONG> returns <STRONG>TRUE</STRONG> if the terminal has insert- and delete-line + capabilities, or can simulate them using scrolling regions. It might + be used to determine whether it would be appropriate to use + <STRONG><A HREF="scrollok.3x.html">scrollok(3x)</A></STRONG> to turn on scrolling. </PRE><H3><a name="h3-killchar_killwchar">killchar, killwchar</a></H3><PRE> - The <STRONG>killchar</STRONG> routine returns the user's current line kill character. + <STRONG>killchar</STRONG> returns the terminal's line kill character. - The <STRONG>killwchar</STRONG> routine stores the current line-kill character in the - location referenced by <EM>wc</EM>. If no line-kill character has been defined, - the routine fails and the location referenced by <EM>wc</EM> is not changed. + <STRONG>killwchar</STRONG> stores the line-kill character in the location referenced by + <EM>wc</EM>. If no line-kill character has been defined, it fails and the + location referenced by <EM>wc</EM> is not changed. </PRE><H3><a name="h3-longname">longname</a></H3><PRE> - The <STRONG>longname</STRONG> routine returns a pointer to a static area containing a - verbose description of the current terminal. The maximum length of a - verbose description is 128 characters. It is defined only after the - call to <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. The area is overwritten by each call to - <STRONG>newterm</STRONG> and is not restored by <STRONG>set_term</STRONG>, so the value should be saved - between calls to <STRONG>newterm</STRONG> if <STRONG>longname</STRONG> is going to be used with multiple - terminals. + <STRONG>longname</STRONG> returns a pointer to static storage containing a verbose + description of the terminal being managed by <EM>curses</EM>. The maximum + length of a verbose description is 128 characters. The storage is + populated only after <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> is called. This + storage is overwritten by each call to <STRONG>newterm</STRONG> and not restored by + <STRONG><A HREF="curs_initscr.3x.html">set_term(3x)</A></STRONG>, so its contents should be saved between calls to <STRONG>initscr</STRONG> + or <STRONG>newterm</STRONG> if <STRONG>longname</STRONG> is to be used with multiple terminals. </PRE><H3><a name="h3-termattrs_term_attrs">termattrs, term_attrs</a></H3><PRE> If a given terminal does not support a video attribute that an - application program is trying to use, <STRONG>curses</STRONG> may substitute a different - video attribute for it. The <STRONG>termattrs</STRONG> and <STRONG>term_attrs</STRONG> functions return - a logical <STRONG>OR</STRONG> of all video attributes supported by the terminal using <STRONG>A_</STRONG> - and <STRONG>WA_</STRONG> constants respectively. This information is useful when a - <STRONG>curses</STRONG> program needs complete control over the appearance of the - screen. + application program is trying to use, <EM>curses</EM> may substitute a different + video attribute for it. <STRONG>termattrs</STRONG> and <STRONG>term_attrs</STRONG> return a logical "or" + of all video attributes supported by the terminal using <STRONG>A_</STRONG> and <STRONG>WA_</STRONG> + constants respectively. This information is useful when a <EM>curses</EM> + program needs complete control over the appearance of the screen. </PRE><H3><a name="h3-termname">termname</a></H3><PRE> - The <STRONG>termname</STRONG> routine returns the terminal name used by <STRONG>setupterm</STRONG>. + <STRONG>termname</STRONG> returns the terminal name used by <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - <STRONG>longname</STRONG> and <STRONG>termname</STRONG> return <STRONG>NULL</STRONG> on error. + <STRONG>longname</STRONG> and <STRONG>termname</STRONG> return <EM>NULL</EM> on error. - Routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4 - only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful - completion. + Functions that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon + success. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Note that <STRONG>termattrs</STRONG> may be a macro. + <STRONG>erasewchar</STRONG>, <STRONG>killwchar</STRONG>, and <STRONG>term_attrs</STRONG> are part of <EM>ncurses</EM>'s wide- + character API, and are not available in its non-wide-character + configuration. + + <STRONG>termattrs</STRONG> may be implemented as a macro. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. It changes the - return type of <STRONG>termattrs</STRONG> to the new type <STRONG>attr_t</STRONG>. Most versions of - curses truncate the result returned by <STRONG>termname</STRONG> to 14 characters. + X/Open Curses Issue 4 describes these functions. + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". + + Most versions of <EM>curses</EM> truncate the string returned by <EM>termname</EM> to 14 + characters. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced <EM>longname</EM>. + SVr2 (1984) added <EM>baudrate</EM>, <EM>erasechar</EM>, <EM>killchar</EM>, <EM>has</EM><STRONG>_</STRONG><EM>ic</EM>, and <EM>has</EM><STRONG>_</STRONG><EM>il</EM>. + + SVr3 (1987) supplied <EM>termname</EM>. Later that year, SVr3.1 brought + <EM>termattrs</EM>. + + X/Open Curses Issue 4 (1995) specified <EM>erasewchar</EM>, <EM>killwchar</EM>, and + <EM>term</EM><STRONG>_</STRONG><EM>attrs</EM>. + + +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> +ncurses 6.6 2025-08-23 <STRONG><A HREF="curs_termattrs.3x.html">curs_termattrs(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -169,6 +182,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="cur <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_termcap.3x.html b/doc/html/man/curs_termcap.3x.html index c2763afe3b94..00e1e8125bd7 100644 --- a/doc/html/man/curs_termcap.3x.html +++ b/doc/html/man/curs_termcap.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2017,2018 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_termcap.3x,v 1.85 2024/04/20 19:13:12 tom Exp @ + * @Id: curs_termcap.3x,v 1.107 2025/08/16 19:09:12 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_termcap 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_termcap 3x 2025-08-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_termcap 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_termcap 3x 2025-08-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>PC</STRONG>, <STRONG>UP</STRONG>, <STRONG>BC</STRONG>, <STRONG>ospeed</STRONG>, <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>, <STRONG>tgetnum</STRONG>, <STRONG>tgetstr</STRONG>, <STRONG>tgoto</STRONG>, <STRONG>tputs</STRONG> - <EM>curses</EM> emulation of <EM>termcap</EM> @@ -60,16 +58,16 @@ <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>BC;</STRONG> <STRONG>short</STRONG> <STRONG>ospeed;</STRONG> - <STRONG>int</STRONG> <STRONG>tgetent(char</STRONG> <STRONG>*</STRONG><EM>bp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>name</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>tgetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>id</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>tgetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>id</EM><STRONG>);</STRONG> - <STRONG>char</STRONG> <STRONG>*tgetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>id</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>**</STRONG><EM>area</EM><STRONG>);</STRONG> - <STRONG>char</STRONG> <STRONG>*tgoto(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>col</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>row</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG> + <STRONG>int</STRONG> <STRONG>tgetent(char</STRONG> <STRONG>*</STRONG> <EM>bp</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>name</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>tgetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>id</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>tgetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>id</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>tgetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>id</EM><STRONG>,</STRONG> <STRONG>char</STRONG> <STRONG>**</STRONG> <EM>sbuf</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>tgoto(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>cap</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>col</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>row</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG> <EM>putc</EM><STRONG>)(int));</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - <EM>ncurses</EM> provides the foregoing variables and functions as a + <EM>ncurses</EM> provides the foregoing variables and functions as a compatibility layer for programs that use the <EM>termcap</EM> library. The API is the same, but behavior is emulated using the <EM>terminfo</EM> database. Thus, it can be used only to query the capabilities of terminal @@ -80,53 +78,53 @@ <STRONG>tgetent</STRONG> loads the terminal database entry for <EM>name</EM>; see <STRONG><A HREF="term.7.html">term(7)</A></STRONG>. This must be done before calling any of the other functions. It returns - 1 on success, + <STRONG>1</STRONG> on success, - 0 if there is no such entry (or if the matching entry describes a - generic terminal, having too little information for <EM>curses</EM> + <STRONG>0</STRONG> if there is no such entry (or if the matching entry describes a + generic terminal, having too little information for <EM>curses</EM> applications to run), and - -1 if the <EM>terminfo</EM> database could not be found. + <STRONG>-1</STRONG> if the <EM>terminfo</EM> database could not be found. This implementation differs from those of historical <EM>termcap</EM> libraries. - <STRONG>o</STRONG> <EM>ncurses</EM> ignores the buffer pointer <EM>bp</EM>, as do other <EM>termcap</EM> - implementations conforming to portions of X/Open Curses now - withdrawn. The BSD <EM>termcap</EM> library would store a copy of the - terminal type description in the area referenced by this - pointer. <EM>terminfo</EM> stores terminal type descriptions in compiled - form, which is not the same thing. + <STRONG>o</STRONG> <EM>ncurses</EM> ignores the buffer pointer <EM>bp</EM>, as do other <EM>termcap</EM> + implementations conforming to portions of X/Open Curses now + withdrawn. The BSD <EM>termcap</EM> library would store a copy of the + terminal type description in the buffer referenced by this pointer. + <EM>terminfo</EM> stores terminal type descriptions in compiled form, which + is not the same thing. - <STRONG>o</STRONG> The meanings of the return values differ. The BSD <EM>termcap</EM> - library does not check whether the terminal type description - includes the <STRONG>generic</STRONG> (<STRONG>gn</STRONG>) capability, nor whether the terminal - type description supports an addressable cursor, a property - essential for any <EM>curses</EM> implementation to operate. + <STRONG>o</STRONG> The meanings of the return values differ. The BSD <EM>termcap</EM> library + does not check whether the terminal type description includes the + <STRONG>generic</STRONG> (<STRONG>gn</STRONG>) capability, nor whether the terminal type description + supports an addressable cursor, a property essential for any <EM>curses</EM> + implementation to operate. </PRE><H3><a name="h3-Retrieving-Capability-Values">Retrieving Capability Values</a></H3><PRE> - <STRONG>tgetflag</STRONG> reports the Boolean entry for <EM>id</EM>, or zero if it is not + <STRONG>tgetflag</STRONG> reports the Boolean entry for <EM>id</EM>, or zero if it is not available. <STRONG>tgetnum</STRONG> obtains the numeric entry for <EM>id</EM>, or -1 if it is not available. - <STRONG>tgetstr</STRONG> returns the string entry for <EM>id</EM>, or <STRONG>NULL</STRONG> if it is not - available. Use <STRONG>tputs</STRONG> to output the string returned. The <EM>area</EM> + <STRONG>tgetstr</STRONG> returns the string entry for <EM>id</EM>, or <EM>NULL</EM> if it is not + available. Use <STRONG>tputs</STRONG> to output the string returned. The <EM>sbuf</EM> parameter is used as follows. - <STRONG>o</STRONG> It is assumed to be the address of a pointer to a buffer managed - by the calling application. + <STRONG>o</STRONG> It is assumed to be the address of a pointer to a buffer managed by + the calling application. - <STRONG>o</STRONG> However, <EM>ncurses</EM> checks to ensure that <EM>area</EM> is not <STRONG>NULL</STRONG>, and - also that the resulting buffer pointer is not <STRONG>NULL</STRONG>. If either - check fails, <EM>area</EM> is ignored. + <STRONG>o</STRONG> However, <EM>ncurses</EM> checks to ensure that <EM>sbuf</EM> is not <EM>NULL</EM>, and that + the pointer obtained by dereferencing <EM>sbuf</EM> is also not <EM>NULL</EM>. If + either check fails, <EM>ncurses</EM> ignores <EM>sbuf</EM>. - <STRONG>o</STRONG> If the checks succeed, <EM>ncurses</EM> also copies the return value to - the buffer pointed to by <EM>area</EM>, and the library updates <EM>area</EM> to - point past the null character terminating this value. + <STRONG>o</STRONG> If the checks succeed, <EM>ncurses</EM> also copies the return value to the + buffer pointed to by <EM>sbuf</EM>, and the library updates <EM>sbuf</EM> to point + past the null character terminating this value. - <STRONG>o</STRONG> The return value itself is an address in the terminal type - description loaded into memory. + <STRONG>o</STRONG> The return value itself is an address in the terminal type + description loaded into memory. </PRE><H3><a name="h3-Applying-String-Capabilities">Applying String Capabilities</a></H3><PRE> @@ -140,18 +138,18 @@ thus be passed to <STRONG>tputs</STRONG> rather than some other output function such as <STRONG>printf(3)</STRONG>. - <STRONG>o</STRONG> While <STRONG>tgoto</STRONG> is assumed to be used for the two-parameter cursor + <STRONG>o</STRONG> While <STRONG>tgoto</STRONG> is assumed to be used for the two-parameter cursor positioning capability, <EM>termcap</EM> applications also use it for single-parameter capabilities. - Doing so reveals a quirk in <STRONG>tgoto</STRONG>: most hardware terminals use - cursor addressing with <EM>row</EM> first, but the original developers of - the <EM>termcap</EM> interface chose to put the <EM>col</EM> (column) parameter - first. The <STRONG>tgoto</STRONG> function swaps the order of its parameters. It - does this even for calls requiring only a single parameter. In + Doing so reveals a quirk in <STRONG>tgoto</STRONG>: most hardware terminals use + cursor addressing with <EM>row</EM> first, but the original developers of + the <EM>termcap</EM> interface chose to put the <EM>col</EM> (column) parameter + first. The <STRONG>tgoto</STRONG> function swaps the order of its parameters. It + does this even for calls requiring only a single parameter. In that case, the first parameter is merely a placeholder. - <STRONG>o</STRONG> Normally the <EM>ncurses</EM> library is compiled without full <EM>termcap</EM> + <STRONG>o</STRONG> Normally the <EM>ncurses</EM> library is compiled without full <EM>termcap</EM> support. In that case, <STRONG>tgoto</STRONG> uses an internal version of <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> (a more capable function). @@ -167,38 +165,39 @@ </PRE><H3><a name="h3-Global-Variables">Global Variables</a></H3><PRE> - The variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG> and <STRONG>BC</STRONG> are set by <STRONG>tgetent</STRONG> to the <EM>terminfo</EM> entry's - data for <STRONG>pad_char</STRONG>, <STRONG>cursor_up</STRONG> and <STRONG>backspace_if_not_bs</STRONG>, respectively. <STRONG>UP</STRONG> - is not used by <EM>ncurses</EM>. <STRONG>PC</STRONG> is used by <STRONG><A HREF="curs_util.3x.html">delay_output(3x)</A></STRONG>. <STRONG>BC</STRONG> is used by - <STRONG>tgoto</STRONG> emulation. The variable <STRONG>ospeed</STRONG> is set by <EM>ncurses</EM> using a system- - specific encoding to indicate the terminal's data rate. + <STRONG>tgetent</STRONG> sets the variables <STRONG>PC</STRONG>, <STRONG>UP</STRONG>, and <STRONG>BC</STRONG> to the <EM>terminfo</EM> entry's data + for <STRONG>pad_char</STRONG> (<STRONG>pad</STRONG>), <STRONG>cursor_up</STRONG> (<STRONG>cuu1</STRONG>), and <STRONG>backspace_if_not_bs</STRONG> (<STRONG>OTbs</STRONG>), + respectively. <EM>ncurses</EM> does not employ <STRONG>cuu1</STRONG> internally. + <STRONG><A HREF="curs_util.3x.html">delay_output(3x)</A></STRONG> uses <STRONG>pad</STRONG>, while <STRONG>tgoto</STRONG> emulation uses the obsolete + <EM>termcap</EM> capability <STRONG>bs</STRONG>, represented in <EM>ncurses</EM> <EM>terminfo</EM> as "OTbs". + <EM>ncurses</EM> assigns the variable <STRONG>ospeed</STRONG> a system-specific value to encode + the terminal's data rate. </PRE><H3><a name="h3-Releasing-Memory">Releasing Memory</a></H3><PRE> The <EM>termcap</EM> functions provide no means of freeing memory, because - legacy <EM>termcap</EM> implementations used only the buffer areas provided by - the caller via <STRONG>tgetent</STRONG> and <STRONG>tgetstr</STRONG>. Those buffers are unused in <EM>term-</EM> - <EM>info</EM>. + legacy <EM>termcap</EM> implementations used only the storage provided by the + caller via <STRONG>tgetent</STRONG> and <STRONG>tgetstr</STRONG>. Those buffers are unused in <EM>terminfo</EM>. - By contrast, <EM>terminfo</EM> allocates memory. It uses <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to - obtain the data used by <STRONG>tgetent</STRONG> and the functions that retrieve + By contrast, <EM>terminfo</EM> allocates memory. It uses <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to + obtain the data used by <STRONG>tgetent</STRONG> and the functions that retrieve capability values. One could use del_curterm(cur_term); - to free this memory, but there is an additional complication with + to free this memory, but there is an additional complication with <EM>ncurses</EM>. It uses a fixed-size pool of storage locations, one per value of the terminal name parameter given to <STRONG>tgetent</STRONG>. The <STRONG>screen(1)</STRONG> program relies upon this arrangement to improve its performance. - An application that uses only the <EM>termcap</EM> functions, not the higher - level <EM>curses</EM> API, could release the memory using <STRONG><A HREF="curs_terminfo.3x.html">del_curterm(3x)</A></STRONG>, + An application that uses only the <EM>termcap</EM> functions, not the higher- + level <EM>curses</EM> API, could release the memory using <STRONG><A HREF="curs_terminfo.3x.html">del_curterm(3x)</A></STRONG>, because the pool is freed using other functions; see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The return values of <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>, <STRONG>tgetname</STRONG>, and <STRONG>tgetstr</STRONG> are + The return values of <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>, <STRONG>tgetname</STRONG>, and <STRONG>tgetstr</STRONG> are documented above. - <STRONG>tgoto</STRONG> returns <STRONG>NULL</STRONG> on error. Error conditions include: + <STRONG>tgoto</STRONG> returns <EM>NULL</EM> on error. Error conditions include: <STRONG>o</STRONG> uninitialized state (<STRONG>tgetent</STRONG> was not called successfully), @@ -206,7 +205,7 @@ <STRONG>o</STRONG> <EM>cap</EM> referring to a canceled capability, - <STRONG>o</STRONG> <EM>cap</EM> being a capability with string-valued parameters (a <EM>term-</EM> + <STRONG>o</STRONG> <EM>cap</EM> being a capability with string-valued parameters (a <EM>term-</EM> <EM>info</EM>-only feature), and <STRONG>o</STRONG> <EM>cap</EM> being a capability with more than two parameters. @@ -215,79 +214,75 @@ </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - <EM>ncurses</EM> compares only the first two characters of the <EM>id</EM> parameter of + <EM>ncurses</EM> compares only the first two characters of the <EM>id</EM> parameter of <STRONG>tgetflag</STRONG>, <STRONG>tgetnum</STRONG>, and <STRONG>tgetstr</STRONG> to the capability names in the database. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are no longer standardized (and the variables never - were); <EM>ncurses</EM> provides them to support legacy applications. They - should not be used in new programs. - + These functions are no longer standardized (and the variables never + were); see section "HISTORY" below. <EM>ncurses</EM> provides them to support + legacy applications; they should not be used in new programs. -</PRE><H3><a name="h3-Standards">Standards</a></H3><PRE> - <STRONG>o</STRONG> X/Open Curses, Issue 4, Version 2 (1996), describes these - functions, marking them as "TO BE WITHDRAWN". - - <STRONG>o</STRONG> X/Open Curses, Issue 7 (2009) marks the <EM>termcap</EM> interface (along - with <STRONG>vwprintw</STRONG> and <STRONG>vwscanw</STRONG>) as withdrawn. + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". Neither X/Open Curses nor the SVr4 man pages documented the return - values of <STRONG>tgetent</STRONG> correctly, though all three shown here were in fact + values of <EM>tgetent</EM> correctly, though all three shown here were in fact returned ever since SVr1. In particular, an omission in the X/Open - Curses specification has been misinterpreted to mean that <STRONG>tgetent</STRONG> - returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. Because the purpose of these functions is to + Curses specification has been misinterpreted to mean that <EM>tgetent</EM> + returns <EM>OK</EM> or <EM>ERR</EM>. Because the purpose of these functions is to provide compatibility with the <EM>termcap</EM> library, that is a defect in - X/Open Curses, Issue 4, Version 2 rather than in <EM>ncurses</EM>. + X/Open Curses Issue 4 Version 2 rather than in <EM>ncurses</EM>. + - <STRONG>Compatibility</STRONG> <STRONG>with</STRONG> <STRONG>BSD</STRONG> <EM>termcap</EM> - Externally visible variables are provided for support of certain +</PRE><H3><a name="h3-Compatibility-with-BSD-termcap">Compatibility with BSD termcap</a></H3><PRE> + <EM>ncurses</EM> provides externally visible variables to support certain <EM>termcap</EM> applications. However, their correct usage is poorly documented; for example, it is unclear when reading and writing them is - meaningful. In particular, some applications are reported to declare - and/or modify <STRONG>ospeed</STRONG>. - - The constraint that only the first two characters of the <EM>id</EM> parameter - are used escapes many application developers. The BSD <EM>termcap</EM> library - did not require a trailing null character on the capability identifier - passed to <STRONG>tgetstr</STRONG>, <STRONG>tgetnum</STRONG>, and <STRONG>tgetflag</STRONG>. Some applications thus - assume that the <EM>termcap</EM> interface does not require the trailing null - character for the capability identifier. - - <STRONG>o</STRONG> <EM>ncurses</EM> disallows matches by the <EM>termcap</EM> interface against extended - capability names that are longer than two characters; see - <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>. - - The BSD <EM>termcap</EM> function <STRONG>tgetent</STRONG> returns the text of a <EM>termcap</EM> entry in - the buffer passed as an argument. This library, like other <EM>terminfo</EM> + meaningful. In particular, some applications are reported to declare + and/or modify <EM>ospeed</EM>. + + The constraint that only the first two characters of the <EM>id</EM> parameter + are looked up in the terminal database escapes many application + developers. The BSD <EM>termcap</EM> library did not require a trailing null + character after the capability identifier passed to <EM>tgetstr</EM>, <EM>tgetnum</EM>, + and <EM>tgetflag</EM>. Some applications thus assume that the <EM>termcap</EM> interface + does not require the trailing null character for the capability + identifier. <EM>ncurses</EM> disallows matches by the <EM>termcap</EM> interface against + extended capability names that are longer than two characters; see + <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>. + + The BSD <EM>termcap</EM> function <EM>tgetent</EM> returns the text of a <EM>termcap</EM> entry in + the buffer passed as an argument. <EM>ncurses</EM>, like other <EM>terminfo</EM> implementations, does not store terminal type descriptions as text. It sets the buffer contents to a null-terminated string. </PRE><H3><a name="h3-Header-File">Header File</a></H3><PRE> - This library includes a <EM>termcap.h</EM> header for compatibility with other - implementations, but the header is rarely used because the other - implementations are not strictly compatible. + <EM>ncurses</EM> includes a <EM>termcap.h</EM> header file for compatibility with other + implementations, but it is rarely used because the other + implementations are not mutually compatible; see below. </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> Bill Joy originated a forerunner of <EM>termcap</EM> called "ttycap", dated September 1977, and released in 1BSD (March 1978). It used many of the - same function names as the later <EM>termcap</EM>, such as <STRONG>tgetent</STRONG>, <STRONG>tgetflag</STRONG>, - <STRONG>tgetnum</STRONG>, and <STRONG>tgetstr</STRONG>. + same function names as the later <EM>termcap</EM>, such as <EM>tgetent</EM>, <EM>tgetflag</EM>, + <EM>tgetnum</EM>, and <EM>tgetstr</EM>. - A clear descendant, the <EM>termlib</EM> library, followed in 2BSD (May 1979), - adding <STRONG>tgoto</STRONG> and <STRONG>tputs</STRONG>. The former applied at that time only to cursor + A clear descendant, the <EM>termlib</EM> library, followed in 2BSD (May 1979), + adding <EM>tgoto</EM> and <EM>tputs</EM>. The former applied at that time only to cursor positioning capabilities, thus the overly specific name. Little changed in 3BSD (late 1979) except the addition of test programs and a <EM>termlib</EM> man page, which documented the API shown in section "SYNOPSIS" above. 4BSD (November 1980) renamed <EM>termlib</EM> to <EM>termcap</EM> and added another test - program. The library remained much the same though 4.3BSD (June 1986). - 4.4BSD-Lite (June 1994) refactored it, leaving the API unchanged. + program. The library remained much the same through 4.3BSD (June + 1986). 4.4BSD-Lite (June 1994) refactored it, leaving the API + unchanged. - Function prototypes were a feature of ANSI C (1989). The library long + Function prototypes were a feature of ANSI C (1989). The library long antedated the standard and thus provided no header file declaring them. Nevertheless, the BSD sources included two different <EM>termcap.h</EM> header files over time. @@ -295,81 +290,84 @@ <STRONG>o</STRONG> One was used internally by <STRONG>jove(1)</STRONG> from 4.3BSD onward. It declared global symbols for the <EM>termcap</EM> variables that it used. - <STRONG>o</STRONG> The other appeared in 4.4BSD-Lite Release 2 (June 1995) as part of - <EM>libedit</EM> (also known as the <EM>editline</EM> library). CSRG source history + <STRONG>o</STRONG> The other appeared in 4.4BSD-Lite Release 2 (June 1995) as part of + <EM>libedit</EM> (also known as the <EM>editline</EM> library). CSRG source history shows that this was added in mid-1992. The <EM>libedit</EM> header file was used internally as a convenience for compiling the <EM>editline</EM> library. It declared function prototypes, but no global variables. - This header file was added to NetBSD's <EM>termcap</EM> library in mid-1994. - - Meanwhile, GNU <EM>termcap</EM> began development in 1990. Its first release - (1.0) in 1991 included a <EM>termcap.h</EM> header. Its second (1.1) in - September 1992 modified the header to use <EM>const</EM> for the function - prototypes in the header where one would expect the parameters to be - read-only. BSD <EM>termcap</EM> did not. The prototype for <STRONG>tputs</STRONG> also - differed, but in that instance, it was <EM>libedit</EM> that differed from BSD + NetBSD's <EM>termcap</EM> library added this header file in mid-1994. + + Meanwhile, GNU <EM>termcap</EM> began development in 1990. Its first release + (1.0) in 1991 included a <EM>termcap.h</EM> header file. Its second (1.1) + release in September 1992 modified the file to use <EM>const</EM> for the + function prototypes in the header where one would expect parameters to + be read-only. BSD <EM>termcap</EM> did not. The prototype for <EM>tputs</EM> also + differed, but in that instance, it was <EM>libedit</EM> that differed from BSD <EM>termcap</EM>. - GNU <EM>termcap</EM> 1.3 was bundled with <STRONG>bash(1)</STRONG> in mid-1993 to support the - <STRONG>readline(3)</STRONG> library. + GNU <STRONG>bash(1)</STRONG> has bundled GNU <EM>termcap</EM> 1.3 since mid-1993 to support its + <STRONG>readline(3)</STRONG> library, and continues to use it if configured to do so. - <EM>ncurses</EM> 1.8.1 (November 1993) provided a <EM>termcap.h</EM> file. It reflected - influence from GNU <EM>termcap</EM> and <STRONG>emacs(1)</STRONG> (rather than <STRONG>jove(1)</STRONG>), + <EM>ncurses</EM> 1.8.1 (November 1993) provided a <EM>termcap.h</EM> file. It reflected + influence from GNU <EM>termcap</EM> and <STRONG>emacs(1)</STRONG> (rather than <STRONG>jove(1)</STRONG>), providing the following interface: <STRONG>o</STRONG> global symbols used by <EM>emacs</EM>, <STRONG>o</STRONG> <EM>const</EM>-qualified function prototypes, and - <STRONG>o</STRONG> a prototype for <STRONG>tparam</STRONG>, a GNU <EM>termcap</EM> feature. + <STRONG>o</STRONG> a prototype for <EM>tparam</EM>, a GNU <EM>termcap</EM> feature. - Later (in mid-1996) the <STRONG>tparam</STRONG> function was removed from <EM>ncurses</EM>. Any - two of the four implementations thus differ, and programs that intend + Later (in mid-1996) the <EM>tparam</EM> function was removed from <EM>ncurses</EM>. Any + two of the four implementations thus differ, and programs that intend to work with all <EM>termcap</EM> library interfaces must account for that fact. + X/Open Curses Issue 4, Version 2 (1996), describes these functions, + marking them as "TO BE WITHDRAWN". + + X/Open Curses Issue 7 (2009) withdrew the <EM>termcap</EM> interface (along with + the <EM>vwprintw</EM> and <EM>vwscanw</EM> functions). + </PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE> If you call <STRONG>tgetstr</STRONG> to fetch <STRONG>column_address</STRONG> (<STRONG>ch</STRONG>) or any other parameterized string capability, be aware that it is returned in <EM>term-</EM> <EM>info</EM> notation, not the older and not-quite-compatible <EM>termcap</EM> notation. - This does not cause problems if all you do with it is call <STRONG>tgoto</STRONG> or - <STRONG>tparm</STRONG>, which both parametrically expand <EM>terminfo</EM>-style string - capabilities as <EM>terminfo</EM> does. (If <EM>ncurses</EM> is configured to support - <EM>termcap,</EM> <STRONG>tgoto</STRONG> checks whether the string is <EM>terminfo</EM>-style by looking - for "<STRONG>%p</STRONG>" parameters or "<STRONG><</STRONG>...<STRONG>></STRONG>" delays, and invokes a <EM>termcap</EM>-style + This does not cause problems if all you do with it is call <STRONG>tgoto</STRONG> or + <STRONG>tparm</STRONG>, which both parametrically expand <EM>terminfo</EM>-style string + capabilities as <EM>terminfo</EM> does. (If <EM>ncurses</EM> is configured to support + <EM>termcap,</EM> <STRONG>tgoto</STRONG> checks whether the string is <EM>terminfo</EM>-style by looking + for "<STRONG>%p</STRONG>" parameters or "<STRONG><</STRONG>...<STRONG>></STRONG>" delays, and invokes a <EM>termcap</EM>-style parser if the string appears not to use <EM>terminfo</EM> syntax.) - Because <EM>terminfo</EM>'s syntax for padding in string capabilities differs + Because <EM>terminfo</EM>'s syntax for padding in string capabilities differs from <EM>termcap</EM>'s, users can be surprised. - <STRONG>o</STRONG> <STRONG>tputs("50")</STRONG> in a <EM>terminfo</EM> system transmits "50" rather than busy- + <STRONG>o</STRONG> <STRONG>tputs("50")</STRONG> in a <EM>terminfo</EM> system transmits "50" rather than busy- waiting for 50 milliseconds. - <STRONG>o</STRONG> However, if <EM>ncurses</EM> is configured to support <EM>termcap</EM>, it may also - have been configured to support BSD-style padding. - - In that case, <STRONG>tputs</STRONG> inspects strings passed to it, looking for - digits at the beginning of the string. + However, if <EM>ncurses</EM> is configured to support <EM>termcap</EM>, it may also + have been configured to support BSD-style padding. In that case, + <STRONG>tputs</STRONG> inspects strings passed to it, looking for digits at the + beginning of the string. - <STRONG>tputs("50")</STRONG> in a <EM>termcap</EM> system may busy-wait for 50 milliseconds + <STRONG>o</STRONG> <STRONG>tputs("50")</STRONG> in a <EM>termcap</EM> system may busy-wait for 50 milliseconds rather than transmitting "50". <EM>termcap</EM> has nothing analogous to <EM>terminfo</EM>'s <STRONG>set_attributes</STRONG> (<STRONG>sgr</STRONG>) capability. One consequence is that <EM>termcap</EM> applications assume that "<STRONG>me</STRONG>" (equivalent to <EM>terminfo</EM>'s <STRONG>exit_attribute_mode</STRONG> (<STRONG>sgr0</STRONG>) capability) - does not reset the alternate character set. <EM>ncurses</EM> checks for, and - modifies the data shared with, the <EM>termcap</EM> interface to accommodate the - latter's limitation in this respect. + does not reset the alternate character set. <EM>ncurses</EM> inspects the data + shared with the <EM>termcap</EM> interface and modifies it as necessary to + accommodate the latter's limitation in this respect. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - https://invisible-island.net/ncurses/tctest.html - + <EM>TCTEST</EM> <EM>--</EM> <EM>A</EM> <EM>Termcap</EM> <EM>Test</EM> <EM>Utility</EM> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG> +ncurses 6.6 2025-08-16 <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -388,7 +386,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="c <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a> <ul> -<li><a href="#h3-Standards">Standards</a></li> +<li><a href="#h3-Compatibility-with-BSD-termcap">Compatibility with BSD termcap</a></li> <li><a href="#h3-Header-File">Header File</a></li> </ul> </li> diff --git a/doc/html/man/curs_terminfo.3x.html b/doc/html/man/curs_terminfo.3x.html index 2bba9d912567..8af1dee6cb04 100644 --- a/doc/html/man/curs_terminfo.3x.html +++ b/doc/html/man/curs_terminfo.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,37 +28,34 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_terminfo.3x,v 1.136 2024/04/14 00:14:40 tom Exp @ + * @Id: curs_terminfo.3x,v 1.176 2025/11/12 01:06:36 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_terminfo 3x 2024-04-13 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_terminfo 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_terminfo 3x 2024-04-13 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_terminfo 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>del_curterm</STRONG>, <STRONG>mvcur</STRONG>, <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>, <STRONG>setupterm</STRONG>, - <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tiparm_s</STRONG>, <STRONG>tiscan_s</STRONG>, <STRONG>tparm</STRONG>, - <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>, <STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> - <EM>curses</EM> interfaces to - <EM>terminfo</EM> database + <STRONG>del_curterm</STRONG>, <STRONG>putp</STRONG>, <STRONG>restartterm</STRONG>, <STRONG>set_curterm</STRONG>, <STRONG>setupterm</STRONG>, <STRONG>tigetflag</STRONG>, + <STRONG>tigetnum</STRONG>, <STRONG>tigetstr</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tiparm_s</STRONG>, <STRONG>tiscan_s</STRONG>, <STRONG>tparm</STRONG>, <STRONG>tputs</STRONG>, <STRONG>vid_attr</STRONG>, + <STRONG>vid_puts</STRONG>, <STRONG>vidattr</STRONG>, <STRONG>vidputs</STRONG> - <EM>curses</EM> interfaces to <EM>terminfo</EM> database </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> <STRONG>#include</STRONG> <STRONG><term.h></STRONG> - <STRONG>TERMINAL</STRONG> <STRONG>*cur_term;</STRONG> + <STRONG>TERMINAL</STRONG> <STRONG>*</STRONG> <STRONG>cur_term;</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolnames[];</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>boolcodes[];</STRONG> @@ -70,95 +67,83 @@ <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strcodes[];</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>const</STRONG> <STRONG>strfnames[];</STRONG> - <STRONG>int</STRONG> <STRONG>setupterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG> - <STRONG>TERMINAL</STRONG> <STRONG>*set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>nterm</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG><EM>oterm</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>restartterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>errret</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>setupterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>errret</EM><STRONG>);</STRONG> + <STRONG>TERMINAL</STRONG> <STRONG>*</STRONG> <STRONG>set_curterm(TERMINAL</STRONG> <STRONG>*</STRONG> <EM>nterm</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>del_curterm(TERMINAL</STRONG> <STRONG>*</STRONG> <EM>oterm</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>restartterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>term</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>filedes</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>errret</EM><STRONG>);</STRONG> - <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG> <EM>/*</EM> <EM>or</EM> <EM>*/</EM> - <STRONG>char</STRONG> <STRONG>*tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>long</STRONG> <EM>p1</EM> ... <STRONG>long</STRONG> <EM>p9</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>tparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>long</STRONG> <EM>p1</EM> ... <STRONG>long</STRONG> <EM>p9</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG> - <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>tputs(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>affcnt</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG> <EM>putc</EM><STRONG>)(int));</STRONG> + <STRONG>int</STRONG> <STRONG>putp(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG> + <STRONG>int</STRONG> <STRONG>vidputs(chtype</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG> <EM>putc</EM><STRONG>)(int));</STRONG> <STRONG>int</STRONG> <STRONG>vidattr(chtype</STRONG> <EM>attrs</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>vid_puts(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG><EM>putc</EM><STRONG>)(int));</STRONG> - <STRONG>int</STRONG> <STRONG>vid_attr(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG><EM>opts</EM><STRONG>);</STRONG> - - <STRONG>int</STRONG> <STRONG>mvcur(int</STRONG> <EM>oldrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>oldcol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>newcol</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>vid_puts(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG> <EM>opts</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>(*</STRONG> <EM>putc</EM><STRONG>)(int));</STRONG> + <STRONG>int</STRONG> <STRONG>vid_attr(attr_t</STRONG> <EM>attrs</EM><STRONG>,</STRONG> <STRONG>short</STRONG> <EM>pair</EM><STRONG>,</STRONG> <STRONG>void</STRONG> <STRONG>*</STRONG> <EM>opts</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>tigetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>tigetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG> - <STRONG>char</STRONG> <STRONG>*tigetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>cap-code</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>tigetflag(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>cap-code</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>tigetnum(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>cap-code</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>tigetstr(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>cap-code</EM><STRONG>);</STRONG> - <STRONG>char</STRONG> <STRONG>*tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>tiparm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> ...<STRONG>);</STRONG> <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM> - <STRONG>char</STRONG> <STRONG>*tiparm_s(int</STRONG> <EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG> - <STRONG>int</STRONG> <STRONG>tiscan_s(int</STRONG> <STRONG>*</STRONG><EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG><EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>str</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>tiparm_s(int</STRONG> <EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>,</STRONG> <STRONG>...);</STRONG> + <STRONG>int</STRONG> <STRONG>tiscan_s(int</STRONG> <STRONG>*</STRONG> <EM>expected</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <STRONG>*</STRONG> <EM>mask</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>str</EM><STRONG>);</STRONG> <EM>/*</EM> <EM>deprecated</EM> <EM>*/</EM> - <STRONG>int</STRONG> <STRONG>setterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>term</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>setterm(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>term</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - These low-level functions must be called by programs that deal directly - with the <EM>terminfo</EM> database to handle certain terminal capabilities, - such as programming function keys. For all other functionality, <EM>curses</EM> - functions are more suitable and their use is recommended. + These lower-level functions of the <EM>curses</EM> standard must be called by + programs that deal directly with the <EM>terminfo</EM> database to handle + certain terminal capabilities, such as programming function keys. For + all other functionality, <EM>curses</EM> functions are more suitable and their + use is recommended. - None of these functions use (or are aware of) multibyte character + None of these functions use (or are aware of) multibyte character strings such as UTF-8. <STRONG>o</STRONG> Capability names and codes use the POSIX portable character set. - <STRONG>o</STRONG> Capability string values have no associated encoding; they are + <STRONG>o</STRONG> Capability string values have no associated encoding; they are strings of 8-bit characters. </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE> - Initially, <STRONG>setupterm</STRONG> should be called. The high-level <EM>curses</EM> functions - <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> call <STRONG>setupterm</STRONG> to initialize the low-level set of - terminal-dependent variables listed in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>. - - Applications can use the terminal capabilities either directly (via - header definitions), or by special functions. The header files - <EM>curses.h</EM> and <EM>term.h</EM> should be included (in that order) to get the - definitions for these strings, numbers, and flags. - - The <EM>terminfo</EM> variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> are initialized by <STRONG>setupterm</STRONG> - as follows. - - <STRONG>o</STRONG> If <STRONG>use_env(FALSE)</STRONG> has been called, values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> - specified in <EM>terminfo</EM> are used. + Call <STRONG>setupterm</STRONG> from your application to have <EM>terminfo</EM> manage the + terminal device; this action initializes the terminal-dependent + variables listed in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>. (A <EM>curses</EM> application calling + <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> achieves the same result.) Applications can + use the terminal capabilities either directly, by object definitions + corresponding to capability names and codes (see <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>) or + by calling the functions documented here. <STRONG>setupterm</STRONG> initializes the + <EM>terminfo</EM> variables <STRONG>lines</STRONG> and <STRONG>columns</STRONG> as described in <STRONG><A HREF="curs_util.3x.html">use_env(3x)</A></STRONG>. - <STRONG>o</STRONG> Otherwise, if the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> exist, - their values are used. If these environment variables do not exist - and the program is running in a window, the current window size is - used. Otherwise, if the environment variables do not exist, the - values for <STRONG>lines</STRONG> and <STRONG>columns</STRONG> specified in the <EM>terminfo</EM> database are - used. + Pass parameterized string capability values through <STRONG>tparm</STRONG> to + instantiate them. All <EM>terminfo</EM> strings (including the output of <STRONG>tparm</STRONG>) + should be sent to the terminal device with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>. Call + <STRONG><A HREF="curs_kernel.3x.html">reset_shell_mode(3x)</A></STRONG> to restore the terminal modes before exiting. (A + <EM>curses</EM> application calling <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> achieves the same result.) - Parameterized strings should be passed through <STRONG>tparm</STRONG> to instantiate - them. All <EM>terminfo</EM> strings (including the output of <STRONG>tparm</STRONG>) should be - sent to the terminal device with <STRONG>tputs</STRONG> or <STRONG>putp</STRONG>. Call <STRONG>reset_shell_mode</STRONG> - to restore the terminal modes before exiting; see <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>. + Programs that use cursor addressing should emit certain capabilities at + specific times. Specifically, output - Programs that use cursor addressing should + <STRONG>o</STRONG> <STRONG>enter_ca_mode</STRONG> upon startup, and - <STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> upon startup and - - <STRONG>o</STRONG> output <STRONG>exit_ca_mode</STRONG> before exiting. + <STRONG>o</STRONG> <STRONG>exit_ca_mode</STRONG> before exiting. Programs that execute shell subprocesses should - <STRONG>o</STRONG> call <STRONG>reset_shell_mode</STRONG> and output <STRONG>exit_ca_mode</STRONG> before the shell is - called and + <STRONG>o</STRONG> call <STRONG><A HREF="curs_kernel.3x.html">reset_shell_mode(3x)</A></STRONG> and output <STRONG>exit_ca_mode</STRONG> before the shell + is called, and - <STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> and call <STRONG>reset_prog_mode</STRONG> after returning from - the shell. + <STRONG>o</STRONG> output <STRONG>enter_ca_mode</STRONG> and call <STRONG><A HREF="curs_kernel.3x.html">reset_prog_mode(3x)</A></STRONG> after returning + from the shell. <STRONG>setupterm</STRONG> reads in the <EM>terminfo</EM> database, initializing the <EM>terminfo</EM> structures, but does not set up the output virtualization structures @@ -168,29 +153,28 @@ environment variable <EM>TERM</EM> is read. <EM>filedes</EM> - is the file descriptor used for getting and setting terminal + is the file descriptor used for getting and setting terminal I/O modes. - Higher-level applications use <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> to initialize the - terminal, passing an output <EM>stream</EM> rather than a <EM>descriptor</EM>. - In <EM>curses</EM>, the two are the same because <STRONG>newterm</STRONG> calls - <STRONG>setupterm</STRONG>, passing the file descriptor derived from its output + Higher-level applications use <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> to initialize the + terminal, passing an output <EM>stream</EM> rather than a <EM>descriptor</EM>. + In <EM>curses</EM>, the two are the same because <STRONG>newterm</STRONG> calls + <STRONG>setupterm</STRONG>, passing the file descriptor derived from its output stream parameter. <EM>errret</EM> - points to an optional location where an error status can be - returned to the caller. If <EM>errret</EM> is not null, then <STRONG>setupterm</STRONG> - returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> and stores a status value in the integer - pointed to by <EM>errret</EM>. A return value of <STRONG>OK</STRONG> combined with + points to an optional location where an error status can be + returned to the caller. If <EM>errret</EM> is not null, then <STRONG>setupterm</STRONG> + returns <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> and stores a status value in the integer + pointed to by <EM>errret</EM>. A return value of <STRONG>OK</STRONG> combined with status of <STRONG>1</STRONG> in <EM>errret</EM> is normal. - If <STRONG>ERR</STRONG> is returned, examine <EM>errret:</EM> - - <STRONG>1</STRONG> means that the terminal is hardcopy, and cannot be used - for <EM>curses</EM> applications. + If <STRONG>ERR</STRONG> is returned, examine <EM>errret</EM>. - <STRONG>setupterm</STRONG> determines if the entry is a hardcopy type by - checking the <STRONG>hardcopy</STRONG> (<STRONG>hc</STRONG>) capability. + <STRONG>1</STRONG> means that the terminal is a hard-copy type (lacks + destructive backspace), and cannot be used for <EM>curses</EM> + applications. The library determines this fact by + checking the terminal type's <STRONG>hardcopy</STRONG> (<STRONG>hc</STRONG>) capability. <STRONG>0</STRONG> means that the terminal could not be found, or that it is a generic type, having too little information for <EM>curses</EM> @@ -204,47 +188,47 @@ If <EM>errret</EM> is null, <STRONG>setupterm</STRONG> reports an error message upon finding an error and exits. Thus, the simplest call is: - setupterm((char *)0, 1, (int *)0); + setupterm((char *) NULL, 1, (int *) NULL); - which uses all the defaults and sends the output to <STRONG>stdout</STRONG>. + which uses all the defaults and sends the output to <EM>stdout</EM>. </PRE><H3><a name="h3-The-Terminal-State">The Terminal State</a></H3><PRE> <STRONG>setupterm</STRONG> stores its information about the terminal in a <EM>TERMINAL</EM> structure pointed to by the global variable <STRONG>cur_term</STRONG>. If it detects an error, or decides that the terminal is unsuitable (hardcopy or - generic), it discards this information, making it not available to + generic), it discards this information, making it unavailable to applications. - If <STRONG>setupterm</STRONG> is called repeatedly for the same terminal type, it will - reuse the information. It maintains only one copy of a given - terminal's capabilities in memory. If it is called for different - terminal types, <STRONG>setupterm</STRONG> allocates new storage for each set of - terminal capabilities. + If <STRONG>setupterm</STRONG> is called repeatedly for the same terminal type, it reuses + the information. It maintains only one copy of a given type's + capabilities in memory. If called for different types, <STRONG>setupterm</STRONG> + allocates new storage for each set of terminal capabilities. - <STRONG>set_curterm</STRONG> sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, and makes all of the <EM>terminfo</EM> - Boolean, numeric, and string variables use the values from <EM>nterm</EM>. It - returns the old value of <STRONG>cur_term</STRONG>. + <STRONG>set_curterm</STRONG> sets <STRONG>cur_term</STRONG> to <EM>nterm</EM>, making all of the <EM>terminfo</EM> Boolean, + numeric, and string capabilities use the values from <EM>nterm</EM>. It returns + the old value of <STRONG>cur_term</STRONG>. - <STRONG>del_curterm</STRONG> frees the space pointed to by <EM>oterm</EM> and makes it available - for further use. If <EM>oterm</EM> is the same as <STRONG>cur_term</STRONG>, references to any - of the <EM>terminfo</EM> Boolean, numeric, and string variables thereafter may - refer to invalid memory locations until another <STRONG>setupterm</STRONG> has been - called. + <STRONG>del_curterm</STRONG> releases the memory pointed to by <EM>oterm</EM>. If <EM>oterm</EM> is the + same as <STRONG>cur_term</STRONG>, references to any of the <EM>terminfo</EM> Boolean, numeric, + and string capabilities thereafter may refer to invalid memory + locations until <STRONG>setupterm</STRONG> is called again. - <STRONG>restartterm</STRONG> is similar to <STRONG>setupterm</STRONG> and <STRONG>initscr</STRONG>, except that it is - called after restoring memory to a previous state (for example, when - reloading a game saved as a core image dump). <STRONG>restartterm</STRONG> assumes that - the windows and the input and output options are the same as when - memory was saved, but the terminal type and baud rate may be different. - Accordingly, <STRONG>restartterm</STRONG> saves various terminal state bits, calls - <STRONG>setupterm</STRONG>, and then restores the bits. + <STRONG>restartterm</STRONG> is similar to <STRONG>setupterm</STRONG>, but is intended for use after + restoring program memory to a previous state (for example, when + reloading an application that has been suspended from one terminal + session and restored in another). <STRONG>restartterm</STRONG> assumes that the display + dimensions and the input and output options are the same as when memory + was saved, but the terminal type and line speed may differ. + Accordingly, <STRONG>restartterm</STRONG> saves relevant terminal state, calls + <STRONG>setupterm</STRONG>, then restores that state. </PRE><H3><a name="h3-Formatting-Output">Formatting Output</a></H3><PRE> - <STRONG>tparm</STRONG> instantiates the string <EM>str</EM> with parameters <EM>pi</EM>. A pointer is - returned to the result of <EM>str</EM> with the parameters applied. Application - developers should keep in mind these quirks of the interface: + <STRONG>tparm</STRONG> instantiates the string <EM>str</EM> with parameters <EM>pi</EM>. It returns a + pointer to a character string representing <EM>str</EM> with the parameters + applied to "%" expressions within. Application developers should keep + in mind some quirks of the interface. <STRONG>o</STRONG> Although <STRONG>tparm</STRONG>'s actual parameters may be integers or strings, the prototype expects <EM>long</EM> (integer) values. @@ -258,18 +242,18 @@ <STRONG>o</STRONG> The capability string is null-terminated. Use "\200" where an ASCII NUL is needed in the output. - <STRONG>tiparm</STRONG> is a newer form of <STRONG>tparm</STRONG> which uses <EM>stdarg.h</EM> rather than a - fixed-parameter list. Its numeric parameters are <EM>int</EM>s rather than + <STRONG>tiparm</STRONG> is a newer form of <STRONG>tparm</STRONG> that uses <EM>stdarg.h</EM> rather than a fixed- + length parameter list. Its numeric parameters are <EM>int</EM>s rather than <EM>long</EM>s. - Both <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> assume that the application passes parameters - consistent with the terminal description. Two extensions are provided - as alternatives to deal with untrusted data. + <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> assume that the application passes parameters + consistent with the terminal description. <EM>ncurses</EM> provides two + extensions as alternatives to deal with untrusted data. - <STRONG>o</STRONG> <STRONG>tiparm_s</STRONG> is an extension which is a safer formatting function than - <STRONG>tparm</STRONG> or <STRONG>tiparm</STRONG>, because it allows the developer to tell the <EM>curses</EM> - library how many parameters to expect in the parameter list, and - which may be string parameters. + <STRONG>o</STRONG> The <STRONG>tiparm_s</STRONG> extension is a safer formatting function than <STRONG>tparm</STRONG> or + <STRONG>tiparm</STRONG>, because it allows the developer to tell the <EM>curses</EM> library + how many parameters to expect in the parameter list, and which may + be string parameters. The <EM>mask</EM> parameter has one bit set for each of the parameters (up to 9) passed as <EM>char</EM> pointers rather than numbers. @@ -279,31 +263,26 @@ </PRE><H3><a name="h3-Output-Functions">Output Functions</a></H3><PRE> - String capabilities can contain padding information, a time delay - (accommodating performance limitations of hardware terminals) expressed - as <STRONG>$<</STRONG><EM>n</EM><STRONG>></STRONG>, where <EM>n</EM> is a nonnegative integral count of milliseconds. If <EM>n</EM> - exceeds 30,000 (thirty seconds), it is capped at that value. - - <STRONG>tputs</STRONG> interprets time-delay information in the string <EM>str</EM> and outputs - it, executing the delays: + String capabilities can contain <EM>padding</EM>, a time delay (accommodating + performance limitations of hardware terminals) expressed as <STRONG>$<</STRONG><EM>n</EM><STRONG>></STRONG>, where + <EM>n</EM> is a nonnegative integral count of milliseconds. If <EM>n</EM> exceeds 30,000 + (thirty seconds), <EM>ncurses</EM> caps it at that value. - <STRONG>o</STRONG> The <EM>str</EM> parameter must be a <EM>terminfo</EM> string variable or the return - value of <STRONG>tparm</STRONG>, <STRONG>tiparm</STRONG>, <STRONG>tgetstr</STRONG>, or <STRONG>tgoto</STRONG>. + <STRONG>tputs</STRONG> interprets time delays in the string <EM>str</EM> and acts upon them. - The <STRONG>tgetstr</STRONG> and <STRONG>tgoto</STRONG> functions are part of the <EM>termcap</EM> interface, - which happens to share these function names with the <EM>terminfo</EM> API. + <STRONG>o</STRONG> The <EM>str</EM> parameter must be a <EM>terminfo</EM> string capability or the + return value of <STRONG>tparm</STRONG> or <STRONG>tiparm</STRONG>. <STRONG>o</STRONG> <EM>affcnt</EM> is the number of lines affected, or <STRONG>1</STRONG> if not applicable. <STRONG>o</STRONG> <EM>putc</EM> is a <EM>putchar</EM>-like function to which the characters are passed, one at a time. - If <STRONG>tputs</STRONG> processes a time-delay, it uses the <STRONG><A HREF="curs_util.3x.html">delay_output(3x)</A></STRONG> - function, routing any resulting padding characters through this - function. + <STRONG>tputs</STRONG> processes each time delay with the <STRONG><A HREF="curs_util.3x.html">delay_output(3x)</A></STRONG> function, + routing any resulting padding characters through this function. <STRONG>putp</STRONG> calls "<STRONG>tputs(</STRONG><EM>str</EM><STRONG>,</STRONG> <STRONG>1,</STRONG> <STRONG>putchar)</STRONG>". The output of <STRONG>putp</STRONG> always goes to - <STRONG>stdout</STRONG>, rather than the <EM>filedes</EM> specified in <STRONG>setupterm</STRONG>. + <EM>stdout</EM>, rather than the <EM>filedes</EM> specified in <STRONG>setupterm</STRONG>. <STRONG>vidputs</STRONG> displays the string on the terminal in the video attribute mode <EM>attrs</EM>, which is any combination of the attributes listed in <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>. @@ -311,37 +290,31 @@ <STRONG>vidattr</STRONG> is like <STRONG>vidputs</STRONG>, except that it outputs through <STRONG>putchar(3)</STRONG>. - <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> correspond to <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG>, respectively. - They use multiple parameters to represent the character attributes and + <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> correspond to <STRONG>vidattr</STRONG> and <STRONG>vidputs</STRONG>, respectively. + They use multiple parameters to represent the character attributes and color; namely, <STRONG>o</STRONG> <EM>attrs</EM>, of type <EM>attr</EM><STRONG>_</STRONG><EM>t</EM>, for the attributes and <STRONG>o</STRONG> <EM>pair</EM>, of type <EM>short</EM>, for the color pair number. - Use the attribute constants prefixed with "<STRONG>WA_</STRONG>" with <STRONG>vid_attr</STRONG> and + Use the attribute constants prefixed with "<STRONG>WA_</STRONG>" with <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG>. - X/Open Curses reserves the <EM>opts</EM> argument for future use, saying that - applications must provide a null pointer for that argument; but see + X/Open Curses reserves the <EM>opts</EM> argument for future use, saying that + applications must provide a null pointer for that argument; but see section "EXTENSIONS" below. - <STRONG>mvcur</STRONG> provides low-level cursor motion. It takes effect immediately - (rather than at the next refresh). Unlike the other low-level output - functions, which either write to the standard output or pass an output - function parameter, <STRONG>mvcur</STRONG> uses an output file descriptor derived from - the output stream parameter of <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>. - - While <STRONG>putp</STRONG> and <STRONG>mvcur</STRONG> are low-level functions that do not use high-level - <EM>curses</EM> state, <EM>ncurses</EM> declares them in <EM>curses.h</EM> because System V did - this (see section "HISTORY" below). + While <STRONG>putp</STRONG> is a lower-level function that does not use higher-level + <EM>curses</EM> state, <EM>ncurses</EM> declares it in <EM>curses.h</EM> because System V did so + (see section "HISTORY" below). </PRE><H3><a name="h3-Terminal-Capability-Functions">Terminal Capability Functions</a></H3><PRE> - <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, and <STRONG>tigetstr</STRONG> return the value of the capability - corresponding to the <EM>terminfo</EM> <EM>cap-code</EM>, such as <STRONG>xenl</STRONG>, passed to them. - The <EM>cap-code</EM> for each capability is given in the table column entitled - <EM>cap-code</EM> code in the capabilities section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. + <STRONG>tigetflag</STRONG>, <STRONG>tigetnum</STRONG>, and <STRONG>tigetstr</STRONG> return the value of the capability + corresponding to the <EM>terminfo</EM> <EM>cap-code</EM>, such as <STRONG>xenl</STRONG>, passed to them. + The <EM>cap-code</EM> for each capability is given in the table column of that + name in the "Capabilities" section of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. These functions return special values to denote errors. @@ -362,7 +335,7 @@ <STRONG>(char</STRONG> <STRONG>*)-1</STRONG> if <EM>cap-code</EM> is not a string capability, or - <STRONG>0</STRONG> if it is canceled or absent from the terminal description. + <STRONG>NULL</STRONG> if it is canceled or absent from the terminal description. </PRE><H3><a name="h3-Terminal-Capability-Names">Terminal Capability Names</a></H3><PRE> @@ -374,7 +347,7 @@ <STRONG>o</STRONG> the long <EM>terminfo</EM> names ("fnames") - for each of the predefined <EM>terminfo</EM> variables: + for each standard <EM>terminfo</EM> capability name. <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*boolnames[]</STRONG>, <STRONG>*boolcodes[]</STRONG>, <STRONG>*boolfnames[]</STRONG> <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*numnames[]</STRONG>, <STRONG>*numcodes[]</STRONG>, <STRONG>*numfnames[]</STRONG> @@ -385,9 +358,7 @@ Each successful call to <STRONG>setupterm</STRONG> allocates memory to hold the terminal description. As a side effect, it sets <STRONG>cur_term</STRONG> to point to this memory. If an application calls - del_curterm(cur_term); - the memory will be freed. The formatting functions <STRONG>tparm</STRONG> and <STRONG>tiparm</STRONG> extend the storage allocated @@ -397,8 +368,8 @@ 6.3, those were shared by all screens. With <EM>ncurses</EM> 6.3, those are allocated per screen. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. - <STRONG>o</STRONG> To improve performance, <EM>ncurses</EM> 6.3 caches the result of analyzing - <EM>terminfo</EM> strings for their parameter types. That is stored as a + <STRONG>o</STRONG> To improve performance, <EM>ncurses</EM> 6.3 caches the result of analyzing + <EM>terminfo</EM> strings for their parameter types. That is stored as a binary tree referenced from the <EM>TERMINAL</EM> structure. The higher-level <STRONG>initscr</STRONG> and <STRONG>newterm</STRONG> functions use <STRONG>setupterm</STRONG>. Normally @@ -407,34 +378,37 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - X/Open Curses defines no failure conditions. In <EM>ncurses</EM>, + Functions that return integers return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon + success. + + In <EM>ncurses</EM>, - <STRONG>del_curtem</STRONG> + <STRONG>del_curterm</STRONG> fails if its terminal parameter is null. <STRONG>putp</STRONG> calls <STRONG>tputs</STRONG>, returning the same error codes. <STRONG>restartterm</STRONG> - fails if the associated call to <STRONG>setupterm</STRONG> returns an error. + fails if the associated call to <STRONG>setupterm</STRONG> returns <STRONG>ERR</STRONG>. <STRONG>setupterm</STRONG> - fails if it cannot allocate enough memory, or create the initial - windows (<STRONG>stdscr</STRONG>, <STRONG>curscr</STRONG>, and <STRONG>newscr</STRONG>) Other error conditions are + fails if it cannot allocate enough memory, or create the initial + windows (<STRONG>stdscr</STRONG>, <STRONG>curscr</STRONG>, and <STRONG>newscr</STRONG>). Other error conditions are documented above. <STRONG>tparm</STRONG> - returns a null pointer if the capability would require unexpected - parameters; that is, too many, too few, or incorrect types + returns a null pointer if the capability would require unexpected + parameters; that is, too many, too few, or incorrect types (strings where integers are expected, or vice versa). <STRONG>tputs</STRONG> - fails if the string parameter is null. It does not detect I/O - errors: X/Open Curses states that <STRONG>tputs</STRONG> ignores the return value + fails if the string parameter is null. It does not detect I/O + errors: X/Open Curses states that <STRONG>tputs</STRONG> ignores the return value of the output function <EM>putc</EM>. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - The <STRONG>vid_attr</STRONG> function in <EM>ncurses</EM> is a special case. It was originally + The <STRONG>vid_attr</STRONG> function in <EM>ncurses</EM> is a special case. It was originally implemented based on a draft of X/Open Curses, as a macro, before other parts of the <EM>ncurses</EM> wide-character API were developed, and unlike the other wide-character functions, is also provided in the non-wide- @@ -442,8 +416,8 @@ </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - The functions marked as extensions were designed for <EM>ncurses</EM>, and are - not found in SVr4 <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> + The functions marked as extensions originated in <EM>ncurses</EM>, and are not + found in SVr4 <EM>curses</EM>, 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> implementation. <EM>ncurses</EM> allows <EM>opts</EM> to be a pointer to <EM>int</EM>, which overrides the <EM>pair</EM> @@ -451,115 +425,124 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - <STRONG>setterm</STRONG> is not described by X/Open and must be considered non-portable. - All other functions are as described by X/Open. + Except for <EM>setterm</EM>, X/Open Curses Issue 4 describes these functions. + It specifies no error conditions for them. + + SVr4 describes a successful return value except where "otherwise noted" + as "an integer value other than <EM>ERR</EM>". + + +</PRE><H3><a name="h3-Header-Files">Header Files</a></H3><PRE> + On legacy <EM>curses</EM> systems, include <EM>curses.h</EM> and <EM>term.h</EM> in that order to + make visible the definitions of the string arrays storing the + capability names and codes. </PRE><H3><a name="h3-Compatibility-Macros">Compatibility Macros</a></H3><PRE> - This implementation provides a few macros for compatibility with - systems before SVr4 (see section "HISTORY" below). They include - <STRONG>Bcrmode</STRONG>, <STRONG>Bfixterm</STRONG>, <STRONG>Bgettmode</STRONG>, <STRONG>Bnocrmode</STRONG>, <STRONG>Bresetterm</STRONG>, <STRONG>Bsaveterm</STRONG>, and - <STRONG>Bsetterm</STRONG>. - - In SVr4, these are found in <EM>curses.h</EM>, but except for <STRONG>setterm</STRONG>, are - likewise macros. The one function, <STRONG>setterm</STRONG>, is mentioned in the manual - page. It further notes that <STRONG>setterm</STRONG> was replaced by <STRONG>setupterm</STRONG>, stating + <EM>ncurses</EM> implements a few macros for early System V <EM>curses</EM> compatibility + (see section "HISTORY" below). They include <EM>crmode</EM>, <EM>fixterm</EM>, <EM>gettmode</EM>, + <EM>nocrmode</EM>, <EM>resetterm</EM>, <EM>saveterm</EM>, and <EM>setterm</EM>. + + In SVr4, these are found in <EM>curses.h</EM>, but except for <EM>setterm</EM>, are + likewise macros. The one function, <EM>setterm</EM>, is mentioned in the manual + page. It further notes that <EM>setterm</EM> was replaced by <EM>setupterm</EM>, stating that the call setupterm(<EM>term</EM>, 1, (int *)0) - provides the same functionality as <STRONG>setterm(</STRONG><EM>term</EM><STRONG>)</STRONG>, discouraging the - latter for new programs. <EM>ncurses</EM> implements each of these symbols as - macros for BSD <EM>curses</EM> compatibility. + provides the same functionality as + setterm(<EM>term</EM>) + and discouraging the latter for new programs. </PRE><H3><a name="h3-Legacy-Data">Legacy Data</a></H3><PRE> - <STRONG>setupterm</STRONG> copies the terminal name to the array <STRONG>ttytype</STRONG>. This is not - part of X/Open Curses, but is assumed by some applications. + <EM>setupterm</EM> copies the terminal name to the array <EM>ttytype</EM>. This behavior + is not specified by X/Open Curses, but is assumed by some applications. - Other implementions may not declare the capability name arrays. Some - provide them without declaring them. X/Open Curses does not specify + Other implementations may not declare the capability name arrays. Some + provide them without declaring them. X/Open Curses does not specify them. - Extended terminal capability names, as defined by "<STRONG>tic</STRONG> <STRONG>-x</STRONG>", are not + Extended terminal capability names, as defined by "<STRONG>tic</STRONG> <STRONG>-x</STRONG>", are not stored in the arrays described here. </PRE><H3><a name="h3-Output-Buffering">Output Buffering</a></H3><PRE> - Older versions of <EM>ncurses</EM> assumed that the file descriptor passed to - <STRONG>setupterm</STRONG> from <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> uses buffered I/O, and would write to - the corresponding stream. In addition to the limitation that the - terminal was left in block-buffered mode on exit (like System V - <EM>curses</EM>), it was problematic because <EM>ncurses</EM> did not allow a reliable - way to clean up on receiving <STRONG>SIGTSTP</STRONG>. + Older versions of <EM>ncurses</EM> assumed that the file descriptor passed to + <EM>setupterm</EM> from <EM>initscr</EM> or <EM>newterm</EM> used buffered I/O, and wrote to the + corresponding <EM>stdio</EM> stream. In addition to the limitation that the + terminal was left in block-buffered mode on exit (like System V + <EM>curses</EM>), it was problematic because <EM>ncurses</EM> did not allow a reliable + way to clean up on receiving <EM>SIGTSTP</EM>. - The current version (ncurses6) uses output buffers managed directly by - <EM>ncurses</EM>. Some of the low-level functions described in this manual page - write to the standard output. They are not signal-safe. The high- - level functions in <EM>ncurses</EM> employ alternate versions of these functions - using the more reliable buffering scheme. + <EM>ncurses</EM> 6.<EM>x</EM> uses output buffers managed directly by <EM>ncurses</EM>. The + lower-level functions described here that write to the terminal device + do so via the standard output stream; they thus are not signal-safe. + The higher-level functions in <EM>ncurses</EM> employ alternate versions of + these functions using a more reliable buffering scheme. </PRE><H3><a name="h3-Function-Prototypes">Function Prototypes</a></H3><PRE> - The X/Open Curses prototypes are based on the SVr4 <EM>curses</EM> header - declarations, which were defined at the same time the C language was + The X/Open Curses prototypes are based on the SVr4 <EM>curses</EM> header + declarations, which were defined at the same time the C language was first standardized in the late 1980s. - <STRONG>o</STRONG> X/Open Curses uses <EM>const</EM> less effectively than a later design - might, sometimes applying it needlessly to values that are already - constant, and in most cases overlooking parameters that normally - would use <EM>const</EM>. Passing <EM>const</EM>-qualified parameters to functions - that do not declare them <EM>const</EM> may prevent the program from - compiling. On the other hand, "writable strings" are an - obsolescent feature. + <STRONG>o</STRONG> X/Open Curses uses <EM>const</EM> less effectively than a later design + might, sometimes applying it needlessly to function parameters that + are passed by value (and therefore copied), and in most cases + overlooking parameters that normally would benefit from <EM>const</EM>. + Passing <EM>const</EM>-qualified parameters to functions that do not declare + them <EM>const</EM> may prevent the program from compiling. On the other + hand, "writable strings" are an obsolescent C language feature. - As an extension, this implementation can be configured to change - the function prototypes to use the <EM>const</EM> keyword. The <EM>ncurses</EM> ABI - 6 enables this feature by default. + As an extension, <EM>ncurses</EM> can be configured to change the function + prototypes to use the <EM>const</EM> keyword. The <EM>ncurses</EM> ABI 6 enables + this feature by default. - <STRONG>o</STRONG> X/Open Curses prototypes <STRONG>tparm</STRONG> with a fixed number of parameters, + <STRONG>o</STRONG> X/Open Curses prototypes <EM>tparm</EM> with a fixed number of parameters, rather than a variable argument list. - This implementation uses a variable argument list, but can be - configured to use the fixed-parameter list. Portable applications - should provide nine parameters after the format; zeroes are fine - for this purpose. + <EM>ncurses</EM> uses a variable argument list, but can be configured to use + the fixed-parameter list. Portable applications should provide + nine parameters after the format; zeroes are fine for this purpose. - In response to review comments by Thomas E. Dickey, X/Open Curses - Issue 7 proposed the <STRONG>tiparm</STRONG> function in mid-2009. + In response to review comments by Thomas E. Dickey, X/Open Curses + Issue 7 proposed the <EM>tiparm</EM> function in mid-2009. - While <STRONG>tiparm</STRONG> is always provided in <EM>ncurses</EM>, the older form is only - available as a build-time configuration option. If not specially - configured, <STRONG>tparm</STRONG> is the same as <STRONG>tiparm</STRONG>. + While <EM>tiparm</EM> is always provided in <EM>ncurses</EM>, the older form is + available only as a build-time configuration option. If not + specially configured, <EM>tparm</EM> is the same as <EM>tiparm</EM>. - Both forms of <STRONG>tparm</STRONG> have drawbacks: + Both forms of <EM>tparm</EM> have drawbacks. - <STRONG>o</STRONG> Most of the calls to <STRONG>tparm</STRONG> use only one or two parameters. Passing + <STRONG>o</STRONG> Most calls to <EM>tparm</EM> require only one or two parameters. Passing nine on each call is awkward. - Using <EM>long</EM> for the numeric parameter type is a workaround to make - the parameter use the same amount of stack as a pointer. That - approach dates back to the mid-1980s, before C was standardized. - Since then, there is a standard (and pointers are not required to - fit in a <EM>long</EM>). + Using <EM>long</EM> for the numeric parameter type is a workaround to make + the parameter use the same amount of stack memory as a pointer. + That approach dates to the mid-1980s, before C was standardized. + Since ANSI C (1989), C language standards do not require a pointer + to fit in a <EM>long</EM>). - <STRONG>o</STRONG> Providing the right number of parameters for a variadic function - such as <STRONG>tiparm</STRONG> can be a problem, in particular for string - parameters. However, only a few <EM>terminfo</EM> capabilities use string - parameters (for instance, the ones used for programmable function + <STRONG>o</STRONG> Providing the right number of parameters for a variadic function + such as <EM>tiparm</EM> can be a problem, in particular for string + parameters. However, only a few <EM>terminfo</EM> capabilities use string + parameters (for instance, the ones used for programmable function keys). The <EM>ncurses</EM> library checks usage of these capabilities, and returns - an error if the capability mishandles string parameters. But it - cannot check if a calling program provides strings in the right - places for the <STRONG>tparm</STRONG> calls. + <EM>ERR</EM> if the capability mishandles string parameters. But it cannot + check if a calling program provides strings in the right places for + the <EM>tparm</EM> calls. + + <EM>ncurses</EM>'s <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> checks its use of these capabilities with a + table, so that it calls <EM>tparm</EM> correctly. - The <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> program checks its use of these capabilities with a - table, so that it calls <STRONG>tparm</STRONG> correctly. - <STRONG>Special</STRONG> <EM>TERM</EM> <STRONG>treatment</STRONG> - If configured to use the terminal driver, as with the MinGW port, +</PRE><H3><a name="h3-Special-TERM-treatment">Special TERM treatment</a></H3><PRE> + If <EM>ncurses</EM> is configured to use a terminal driver that does not employ + the POSIX <EM>termios</EM> API, as with the MinGW port, - <STRONG>o</STRONG> <STRONG>setupterm</STRONG> interprets a missing/empty <EM>TERM</EM> variable as the special - value "unknown". + <STRONG>o</STRONG> <EM>setupterm</EM> interprets a missing or empty <EM>TERM</EM> variable as the + special value "unknown". SVr4 <EM>curses</EM> uses the special value "dumb". @@ -567,128 +550,113 @@ <STRONG>generic_type</STRONG> (<STRONG>gn</STRONG>) <EM>terminfo</EM> capability, while the latter does not. A generic terminal is unsuitable for full-screen applications. - <STRONG>o</STRONG> <STRONG>setupterm</STRONG> allows explicit use of the the windows console driver by - checking if <STRONG>$TERM</STRONG> is set to "#win32con" or an abbreviation of that - string. + <STRONG>o</STRONG> <EM>setupterm</EM> allows explicit use of the Microsoft Windows console + driver by checking whether the <EM>TERM</EM> environment variable has the + value "#win32con" or an abbreviation of that string. </PRE><H3><a name="h3-Other-Portability-Issues">Other Portability Issues</a></H3><PRE> - In SVr4, <STRONG>set_curterm</STRONG> returns an <EM>int</EM>, <STRONG>OK</STRONG> or <STRONG>ERR</STRONG>. We have chosen to + In SVr4, <EM>set</EM><STRONG>_</STRONG><EM>curterm</EM> returns an <EM>int</EM>, <EM>OK</EM> or <EM>ERR</EM>. We have chosen to implement the X/Open Curses semantics. - In SVr4, the third argument of <STRONG>tputs</STRONG> has the type "<STRONG>int</STRONG> <STRONG>(*putc)(char)</STRONG>". - - At least one implementation of X/Open Curses (Solaris) returns a value - other than <STRONG>OK</STRONG> or <STRONG>ERR</STRONG> from <STRONG>tputs</STRONG>. It instead returns the length of the - string, and does no error checking. + In SVr4, the third argument of <EM>tputs</EM> has the type "<STRONG>int</STRONG> <STRONG>(*)(char)</STRONG>". - X/Open Curses notes that after calling <STRONG>mvcur</STRONG>, the <EM>curses</EM> state may not - match the actual terminal state, and that an application should touch - and refresh the window before resuming normal <EM>curses</EM> calls. Both - <EM>ncurses</EM> and SVr4 <EM>curses</EM> implement <STRONG>mvcur</STRONG> using the <EM>SCREEN</EM> data allocated - in either <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG>. So though it is documented as a <EM>terminfo</EM> - function, <STRONG>mvcur</STRONG> is really a <EM>curses</EM> function that is not well specified. + At least one implementation of X/Open Curses (Solaris <EM>xcurses</EM>) returns + a value other than <EM>OK</EM> or <EM>ERR</EM> from <EM>tputs</EM>. It instead returns the length + of the string, and does no error checking. - X/Open Curses states that the old location must be given for <STRONG>mvcur</STRONG> to - accommodate terminals that lack absolute cursor positioning. <EM>ncurses</EM> - allows the caller to use -1 for either or both old coordinates. The -1 - tells <EM>ncurses</EM> that the old location is unknown, and that it must use - only absolute motion, as with the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>) capability, - rather than the least costly combination of absolute and relative - motion. + Very old versions of AIX <EM>curses</EM> required inclusion of <EM>curses.h</EM> before + <EM>term.h</EM>. </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - SVr2 (1984) introduced the <EM>terminfo</EM> feature. Its programming manual + SVr2 (1984) introduced the <EM>terminfo</EM> feature. Its programming manual mentioned the following low-level functions. <STRONG>Function</STRONG> <STRONG>Description</STRONG> ------------------------------------------------------------------------ - <STRONG>fixterm</STRONG> restore terminal to "in <EM>curses</EM>" state - <STRONG>gettmode</STRONG> establish current terminal modes - <STRONG>mvcur</STRONG> low level cursor motion - <STRONG>putp</STRONG> use <STRONG>tputs</STRONG> to send characters via <EM>putchar</EM> - <STRONG>resetterm</STRONG> set terminal modes to "out of <EM>curses</EM>" state - - <STRONG>resetty</STRONG> reset terminal flags to stored value - <STRONG>saveterm</STRONG> save current modes as "in <EM>curses</EM>" state - <STRONG>savetty</STRONG> store current terminal flags - <STRONG>setterm</STRONG> establish terminal with given type - <STRONG>setupterm</STRONG> establish terminal with given type - <STRONG>tparm</STRONG> interpolate parameters into string capability - <STRONG>tputs</STRONG> apply padding information to a string - <STRONG>vidattr</STRONG> like <STRONG>vidputs</STRONG>, but output through <EM>putchar</EM> - <STRONG>vidputs</STRONG> write string to terminal, applying specified attributes - - The programming manual also mentioned functions provided for <EM>termcap</EM> + <EM>fixterm</EM> restore terminal to "in <EM>curses</EM>" state + <EM>gettmode</EM> establish current terminal modes + <EM>mvcur</EM> low level cursor motion + <EM>putp</EM> use <EM>tputs</EM> to send characters via <EM>putchar</EM> + <EM>resetterm</EM> set terminal modes to "out of <EM>curses</EM>" state + <EM>resetty</EM> reset terminal flags to stored value + <EM>saveterm</EM> save current modes as "in <EM>curses</EM>" state + <EM>savetty</EM> store current terminal flags + <EM>setterm</EM> establish terminal with given type + <EM>setupterm</EM> establish terminal with given type + <EM>tparm</EM> interpolate parameters into string capability + <EM>tputs</EM> apply padding information to a string + <EM>vidattr</EM> like <EM>vidputs</EM>, but output through <EM>putchar</EM> + <EM>vidputs</EM> write string to terminal, applying specified attributes + + The programming manual also mentioned functions provided for <EM>termcap</EM> compatibility (commenting that they "may go away at a later date"). <STRONG>Function</STRONG> <STRONG>Description</STRONG> ------------------------------------------------------------------------ - <STRONG>tgetent</STRONG> look up <EM>termcap</EM> entry for given <EM>name</EM> - <STRONG>tgetflag</STRONG> get Boolean entry for given <EM>id</EM> - <STRONG>tgetnum</STRONG> get numeric entry for given <EM>id</EM> - <STRONG>tgetstr</STRONG> get string entry for given <EM>id</EM> - <STRONG>tgoto</STRONG> apply parameters to given capability - <STRONG>tputs</STRONG> write characters via a function parameter, applying padding + <EM>tgetent</EM> look up <EM>termcap</EM> entry for given <EM>name</EM> + <EM>tgetflag</EM> get Boolean entry for given <EM>id</EM> + <EM>tgetnum</EM> get numeric entry for given <EM>id</EM> + <EM>tgetstr</EM> get string entry for given <EM>id</EM> + <EM>tgoto</EM> apply parameters to given capability + <EM>tputs</EM> write characters via a function parameter, applying padding - Early <EM>terminfo</EM> programs obtained capability values from the <EM>TERMINAL</EM> - structure initialized by <STRONG>setupterm</STRONG>. + Early <EM>terminfo</EM> programs obtained capability values from the <EM>TERMINAL</EM> + structure initialized by <EM>setupterm</EM>. - SVr3 (1987) extended <EM>terminfo</EM> by adding functions to retrieve - capability values (like the <EM>termcap</EM> interface), and reusing <STRONG>tgoto</STRONG> and - <STRONG>tputs</STRONG>. + SVr3 (1987) extended <EM>terminfo</EM> by adding functions to retrieve + capability values (like the <EM>termcap</EM> interface), and reusing <EM>tgoto</EM> and + <EM>tputs</EM>. <STRONG>Function</STRONG> <STRONG>Description</STRONG> ------------------------------------------------------------------------ - <STRONG>tigetflag</STRONG> get Boolean entry for given <EM>id</EM> - <STRONG>tigetnum</STRONG> get numeric entry for given <EM>id</EM> - <STRONG>tigetstr</STRONG> get string entry for given <EM>id</EM> + <EM>tigetflag</EM> get Boolean entry for given <EM>id</EM> + <EM>tigetnum</EM> get numeric entry for given <EM>id</EM> + <EM>tigetstr</EM> get string entry for given <EM>id</EM> - SVr3 also replaced several of the SVr2 <EM>terminfo</EM> functions that had no + SVr3 also replaced several of the SVr2 <EM>terminfo</EM> functions that had no counterpart in the <EM>termcap</EM> interface, documenting them as obsolete. <STRONG>Function</STRONG> <STRONG>Replaced</STRONG> <STRONG>by</STRONG> ------------------------------------------------------------------------ - crmode cbreak - fixterm reset_prog_mode - gettmode <EM>n/a</EM> - nocrmode nocbreak - resetterm reset_shell_mode - saveterm def_prog_mode - setterm setupterm - - SVr3 kept the <STRONG>mvcur</STRONG>, <STRONG>vidattr</STRONG>, and <STRONG>vidputs</STRONG> functions, along with <STRONG>putp</STRONG>, - <STRONG>tparm</STRONG>, and <STRONG>tputs</STRONG>. The latter were needed to support padding, and to - handle capabilities accessed by functions such as <STRONG>vidattr</STRONG> (which used - more than the two parameters supported by <STRONG>tgoto</STRONG>). - - SVr3 introduced the functions for switching between terminal - descriptions; for example, <STRONG>set_curterm</STRONG>. Some changes reflected + <EM>crmode</EM> <EM>cbreak</EM> + <EM>fixterm</EM> <EM>reset</EM><STRONG>_</STRONG><EM>prog</EM><STRONG>_</STRONG><EM>mode</EM> + <EM>gettmode</EM> n/a + <EM>nocrmode</EM> <EM>nocbreak</EM> + <EM>resetterm</EM> <EM>reset</EM><STRONG>_</STRONG><EM>shell</EM><STRONG>_</STRONG><EM>mode</EM> + <EM>saveterm</EM> <EM>def</EM><STRONG>_</STRONG><EM>prog</EM><STRONG>_</STRONG><EM>mode</EM> + <EM>setterm</EM> <EM>setupterm</EM> + + SVr3 kept the <EM>mvcur</EM>, <EM>vidattr</EM>, and <EM>vidputs</EM> functions, along with <EM>putp</EM>, + <EM>tparm</EM>, and <EM>tputs</EM>. The latter were needed to support padding, and to + handle capabilities accessed by functions such as <EM>vidattr</EM> (which used + more than the two parameters supported by <EM>tgoto</EM>). + + SVr3 introduced the functions for switching between terminal + descriptions; for example, <EM>set</EM><STRONG>_</STRONG><EM>curterm</EM>. Some changes reflected incremental improvements to the SVr2 library. - <STRONG>o</STRONG> The <EM>TERMINAL</EM> type definition was introduced in SVr3.01, for the + <STRONG>o</STRONG> The <EM>TERMINAL</EM> type definition was introduced in SVr3.01, for the <EM>term</EM> structure provided in SVr2. - <STRONG>o</STRONG> Various global variables such as <STRONG>boolnames</STRONG> were mentioned in the - programming manual at this point, though the variables had been + <STRONG>o</STRONG> Various global variables such as <EM>boolnames</EM> were mentioned in the + programming manual at this point, though the variables had been provided in SVr2. - SVr4 (1989) added the <STRONG>vid_attr</STRONG> and <STRONG>vid_puts</STRONG> functions. + SVr4 (1989) added the <EM>vid</EM><STRONG>_</STRONG><EM>attr</EM> and <EM>vid</EM><STRONG>_</STRONG><EM>puts</EM> functions. - Other low-level functions are declared in the <EM>curses</EM> header files of - Unix systems, but none are documented. Those noted as "obsolete" by + Other low-level functions are declared in the <EM>curses</EM> header files of + Unix systems, but none are documented. Those noted as "obsolete" by SVr3 remained in use by System V's <STRONG>vi(1)</STRONG> editor. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>, - <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, + <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>putc(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - -ncurses 6.5 2024-04-13 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -710,10 +678,12 @@ ncurses 6.5 2024-04-13 <STRONG><A HREF="cu <li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a> <ul> +<li><a href="#h3-Header-Files">Header Files</a></li> <li><a href="#h3-Compatibility-Macros">Compatibility Macros</a></li> <li><a href="#h3-Legacy-Data">Legacy Data</a></li> <li><a href="#h3-Output-Buffering">Output Buffering</a></li> <li><a href="#h3-Function-Prototypes">Function Prototypes</a></li> +<li><a href="#h3-Special-TERM-treatment">Special TERM treatment</a></li> <li><a href="#h3-Other-Portability-Issues">Other Portability Issues</a></li> </ul> </li> diff --git a/doc/html/man/curs_threads.3x.html b/doc/html/man/curs_threads.3x.html index 8681a8fe8305..efebf018c8c8 100644 --- a/doc/html/man/curs_threads.3x.html +++ b/doc/html/man/curs_threads.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2021-2023,2024 Thomas E. Dickey * + * Copyright 2021-2024,2025 Thomas E. Dickey * * Copyright 2008-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_threads.3x,v 1.56 2024/03/16 15:35:01 tom Exp @ + * @Id: curs_threads.3x,v 1.59 2025/02/15 19:41:22 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_threads 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_threads 3x 2025-02-15 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_threads 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_threads 3x 2025-02-15 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <EM>NCURSES</EM><STRONG>_</STRONG><EM>WINDOW</EM><STRONG>_</STRONG><EM>CB</EM>, <EM>NCURSES</EM><STRONG>_</STRONG><EM>SCREEN</EM><STRONG>_</STRONG><EM>CB</EM>, <STRONG>get_escdelay</STRONG>, <STRONG>set_escdelay</STRONG>, <STRONG>set_tabsize</STRONG>, <STRONG>use_screen</STRONG>, <STRONG>use_window</STRONG> - <EM>curses</EM> support for multi-threaded @@ -70,7 +68,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The <EM>ncurses</EM> library can be configured to support multi-threaded - applications in a rudimentary way. Such configuration produces a + applications in a rudimentary way. Such configuration produces a different set of libraries, named <EM>libncursest</EM>, for example, since doing so alters <EM>ncurses</EM>'s application binary interface (ABI). @@ -80,32 +78,32 @@ <EM>mutexes</EM> (mutual exclusion locks) needed to prevent concurrent access to variables shared by multiple threads of execution. - <EM>ncurses</EM> threading support requires the use of functions to access - members of the <EM>WINDOW</EM> structure (see <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>). It further - makes functions of the common global variables <STRONG>COLORS</STRONG>, <STRONG>COLOR_PAIRS</STRONG>, - <STRONG>COLS</STRONG>, <STRONG>ESCDELAY</STRONG>, <STRONG>LINES</STRONG>, <STRONG>TABSIZE</STRONG>, <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>, and <STRONG>ttytype</STRONG>, - maintaining them as as read-only values in the <EM>SCREEN</EM> structure. - - Even this is not enough to make an application using <EM>curses</EM> thread- - safe. We would expect a multi-threaded application to have threads - updating separate windows (on the same device), and separate screens - (on different devices). Further, applications expect a few of the - global variables to be writable. The functions described here address + <EM>ncurses</EM> threading support requires the use of functions to access + members of the <EM>WINDOW</EM> structure (see <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>). It further + makes functions of the common global variables <STRONG>COLORS</STRONG>, <STRONG>COLOR_PAIRS</STRONG>, + <STRONG>COLS</STRONG>, <STRONG>ESCDELAY</STRONG>, <STRONG>LINES</STRONG>, <STRONG>TABSIZE</STRONG>, <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>, and <STRONG>ttytype</STRONG>, + maintaining them as read-only values in the <EM>SCREEN</EM> structure. + + Even this is not enough to make an application using <EM>curses</EM> thread- + safe. We would expect a multi-threaded application to have threads + updating separate windows (on the same device), and separate screens + (on different devices). Further, applications expect a few of the + global variables to be writable. The functions described here address these special situations. The <STRONG>ESCDELAY</STRONG> and <STRONG>TABSIZE</STRONG> global variables are modified by some - applications. To modify them in any configuration, use the - <STRONG>set_escdelay</STRONG> or <STRONG>set_tabsize</STRONG> functions. Other global variables are not + applications. To modify them in any configuration, use the + <STRONG>set_escdelay</STRONG> or <STRONG>set_tabsize</STRONG> functions. Other global variables are not modifiable. <STRONG>get_escdelay</STRONG> retrieves <STRONG>ESCDELAY</STRONG>'s value. - The <STRONG>use_window</STRONG> and <STRONG>use_screen</STRONG> functions provide coarse-grained mutexes - for their respective <EM>WINDOW</EM> and <EM>SCREEN</EM> parameters; they call a user- - supplied function, pass it a <EM>data</EM> parameter, and return the value from + The <STRONG>use_window</STRONG> and <STRONG>use_screen</STRONG> functions provide coarse-grained mutexes + for their respective <EM>WINDOW</EM> and <EM>SCREEN</EM> parameters; they call a user- + supplied function, pass it a <EM>data</EM> parameter, and return the value from the user-supplied function to the application. </PRE><H3><a name="h3-Usage">Usage</a></H3><PRE> - All <EM>ncurses</EM> library functions assume that the locale is not altered + All <EM>ncurses</EM> library functions assume that the locale is not altered during operation. In addition, they use data that is maintained within a hierarchy of scopes. @@ -179,7 +177,6 @@ <STRONG>box_set</STRONG> window (<STRONG>stdscr</STRONG>) <STRONG>can_change_color</STRONG> terminal <STRONG>cbreak</STRONG> screen - <STRONG>chgat</STRONG> window (<STRONG>stdscr</STRONG>) <STRONG>clear</STRONG> window (<STRONG>stdscr</STRONG>) <STRONG>clearok</STRONG> window @@ -246,7 +243,6 @@ <STRONG>immedok</STRONG> window <STRONG>in_wch</STRONG> window (<STRONG>stdscr</STRONG>) <STRONG>in_wchnstr</STRONG> window (<STRONG>stdscr</STRONG>) - <STRONG>in_wchstr</STRONG> window (<STRONG>stdscr</STRONG>) <STRONG>inch</STRONG> window (<STRONG>stdscr</STRONG>) <STRONG>inchnstr</STRONG> window (<STRONG>stdscr</STRONG>) @@ -313,7 +309,6 @@ <STRONG>mvderwin</STRONG> window (<STRONG>stdscr</STRONG>) <STRONG>mvget_wch</STRONG> screen (input operation) <STRONG>mvget_wstr</STRONG> screen (input operation) - <STRONG>mvgetch</STRONG> screen (input operation) <STRONG>mvgetn_wstr</STRONG> screen (input operation) <STRONG>mvgetnstr</STRONG> screen (input operation) @@ -380,7 +375,6 @@ <STRONG>mvwprintw</STRONG> window <STRONG>mvwscanw</STRONG> screen <STRONG>mvwvline</STRONG> window - <STRONG>mvwvline_set</STRONG> window <STRONG>napms</STRONG> reentrant <STRONG>newpad</STRONG> global (locks window list) @@ -447,7 +441,6 @@ <STRONG>slk_clear</STRONG> screen <STRONG>slk_color</STRONG> screen <STRONG>slk_init</STRONG> screen - <STRONG>slk_label</STRONG> screen <STRONG>slk_noutrefresh</STRONG> screen <STRONG>slk_refresh</STRONG> screen @@ -514,7 +507,6 @@ <STRONG>waddnstr</STRONG> window <STRONG>waddnwstr</STRONG> window <STRONG>waddstr</STRONG> window - <STRONG>waddwstr</STRONG> window <STRONG>wattr_get</STRONG> window <STRONG>wattr_off</STRONG> window @@ -581,7 +573,6 @@ <STRONG>wscanw</STRONG> screen <STRONG>wscrl</STRONG> window <STRONG>wsetscrreg</STRONG> window - <STRONG>wstandend</STRONG> window <STRONG>wstandout</STRONG> window <STRONG>wsyncdown</STRONG> screen (affects window plus parents) @@ -615,9 +606,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> +ncurses 6.6 2025-02-15 <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_touch.3x.html b/doc/html/man/curs_touch.3x.html index 50717662864c..b2e9adcdbf5e 100644 --- a/doc/html/man/curs_touch.3x.html +++ b/doc/html/man/curs_touch.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_touch.3x,v 1.47 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_touch.3x,v 1.63 2025/01/19 00:51:10 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_touch 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_touch 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_touch 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_touch 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>touchwin</STRONG>, <STRONG>touchline</STRONG>, <STRONG>untouchwin</STRONG>, <STRONG>wtouchln</STRONG>, <STRONG>is_linetouched</STRONG>, <STRONG>is_wintouched</STRONG> - control terminal output refresh in a <EM>curses</EM> window @@ -69,10 +67,10 @@ The <STRONG>touchwin</STRONG> and <STRONG>touchline</STRONG> routines throw away all optimization information about which parts of the window have been touched, by pretending that the entire window has been drawn on. This is sometimes - necessary when using overlapping windows, since a change to one window - affects the other window, but the records of which lines have been - changed in the other window do not reflect the change. The routine - <STRONG>touchline</STRONG> only pretends that <EM>count</EM> lines have been changed, beginning + necessary when using overlapping windows, since a change to one window + affects the other window, but the records of which lines have been + changed in the other window do not reflect the change. The routine + <STRONG>touchline</STRONG> only pretends that <EM>count</EM> lines have been changed, beginning with line <EM>start</EM>. The <STRONG>untouchwin</STRONG> routine marks all lines in the window as unchanged since @@ -89,19 +87,17 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - All routines return the integer <STRONG>ERR</STRONG> upon failure and an integer value - other than <STRONG>ERR</STRONG> upon successful completion, unless otherwise noted in - the preceding routine descriptions. + Functions returning integers return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon + success. - X/Open Curses does not specify any error conditions. In this - implementation + In <EM>ncurses</EM>, <STRONG>is_linetouched</STRONG> - returns an error if the window pointer is null, or if the line + returns <STRONG>ERR</STRONG> if the window pointer is null, or if the line number is outside the window boundaries. The constant <STRONG>ERR</STRONG> is distinct from <STRONG>TRUE</STRONG> and <STRONG>FALSE</STRONG>, which are the - normal return values of this function. Because the function + normal return values of this function. Because the function returns a <STRONG>bool</STRONG>, returning <STRONG>ERR</STRONG> (which is neither <STRONG>TRUE</STRONG> nor <STRONG>FALSE</STRONG>) may not be supported by the compiler. @@ -110,31 +106,35 @@ The actual function returns <STRONG>FALSE</STRONG> when it detects an error. <STRONG>wtouchln</STRONG> - returns an error if the window pointer is null, or if the line + returns <STRONG>ERR</STRONG> if the window pointer is null, or if the line number is outside the window boundaries. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - All of these routines except <STRONG>wtouchln</STRONG> may be macros. + All of these functions except <STRONG>wtouchln</STRONG> may be implemented as macros. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions were introduced by SVr4. The Solaris <EM>curses</EM> header - file, for instance, defines both an actual function and macro for each. - The macros give the same result as the actual functions. SVr4 <EM>curses</EM> - does not check the window parameter <EM>win</EM> to ensure that it is not <STRONG>NULL</STRONG>; - otherwise this implementation behaves the same as SVr4. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. - X/Open Curses, Issue 4 describes these functions, but defines no error - conditions. + SVr4 describes a successful return value except where "otherwise noted" + as "an integer value other than <EM>ERR</EM>". + SVr4 does not check <EM>win</EM> to ensure that it is not a null pointer. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + SVr2 (1984) introduced <EM>touchwin</EM>, + SVr3 (1987) added <EM>touchline</EM>. SVr3.1 later that year supplied + <EM>is</EM><STRONG>_</STRONG><EM>linetouched</EM>, <EM>is</EM><STRONG>_</STRONG><EM>wintouched</EM>, <EM>untouchwin</EM>, and <EM>wtouchln</EM>. + + +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -144,6 +144,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF= <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_trace.3x.html b/doc/html/man/curs_trace.3x.html index c1ea937fd64b..244861dd2a6a 100644 --- a/doc/html/man/curs_trace.3x.html +++ b/doc/html/man/curs_trace.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 2000-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_trace.3x,v 1.50 2024/04/20 21:24:19 tom Exp @ + * @Id: curs_trace.3x,v 1.55 2025/01/19 00:51:10 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_trace 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_trace 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_trace 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_trace 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>curses_trace</STRONG>, <STRONG>trace</STRONG>, <STRONG>_tracef</STRONG>, <STRONG>_traceattr</STRONG>, <STRONG>_traceattr2</STRONG>, <STRONG>_tracecchar_t</STRONG>, <STRONG>_tracecchar_t2</STRONG>, <STRONG>_tracechar</STRONG>, <STRONG>_tracechtype</STRONG>, <STRONG>_tracechtype2</STRONG>, <STRONG>_nc_tracebits</STRONG>, @@ -83,10 +81,10 @@ <STRONG>o</STRONG> Aside from <STRONG>curses_trace</STRONG>, the other functions are normally available only with the debugging library e.g., <STRONG>libncurses_g.a</STRONG>. - All of the trace functions may be compiled into any model (shared, + All of the trace functions may be compiled into any model (shared, static, profile) by defining the symbol <STRONG>TRACE</STRONG>. - <STRONG>o</STRONG> Additionally, the functions which use <STRONG>cchar_t</STRONG> are only available + <STRONG>o</STRONG> Additionally, the functions which use <STRONG>cchar_t</STRONG> are only available with the wide-character configuration of the libraries. @@ -100,8 +98,8 @@ The other functions either return a pointer to a string-area (allocated by the corresponding function), or return no value (such - as <STRONG>_tracedump</STRONG>, which implements the screen dump for <STRONG>TRACE_UPDATE</STRONG>). - The caller should not free these strings, since the allocation is + as <STRONG>_tracedump</STRONG>, which implements the screen dump for <STRONG>TRACE_UPDATE</STRONG>). + The caller should not free these strings, since the allocation is reused on successive calls. To work around the problem of a single string-area per function, some use a buffer-number parameter, telling the library to allocate additional string-areas. @@ -109,8 +107,8 @@ The <STRONG>curses_trace</STRONG> function is always available, whether or not the other trace functions are available: - <STRONG>o</STRONG> If tracing is available, calling <STRONG>curses_trace</STRONG> with a nonzero - parameter updates the trace mask, and returns the previous trace + <STRONG>o</STRONG> If tracing is available, calling <STRONG>curses_trace</STRONG> with a nonzero + parameter updates the trace mask, and returns the previous trace mask. When the trace mask is nonzero, <EM>ncurses</EM> creates the file "trace" in @@ -121,8 +119,8 @@ </PRE><H3><a name="h3-Trace-Parameter">Trace Parameter</a></H3><PRE> - The trace parameter is formed by OR'ing values from the list of - <STRONG>TRACE_</STRONG><EM>xxx</EM> definitions in <STRONG><curses.h></STRONG>. These include: + The trace parameter is formed by logically "or"-ing values from the + list of <STRONG>TRACE_</STRONG><EM>xxx</EM> definitions in <STRONG><curses.h></STRONG>. These include: <STRONG>TRACE_DISABLE</STRONG> turn off tracing by passing a zero parameter. @@ -198,19 +196,19 @@ <STRONG>o</STRONG> messages produced by the underlying library are written to <EM>trace</EM>. - If <EM>ncurses</EM> is built without tracing, none of the latter are produced, + If <EM>ncurses</EM> is built without tracing, none of the latter are produced, and fewer diagnostics are provided by the command-line utilities. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Routines which return a value are designed to be used as parameters to + Routines which return a value are designed to be used as parameters to the <STRONG>_tracef</STRONG> routine. </PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE> </PRE><H3><a name="h3-NCURSES_TRACE">NCURSES_TRACE</a></H3><PRE> - A positive integral value stored in this variable causes the following + A positive integral value stored in this variable causes the following functions to enable the tracing feature as if <STRONG>curses_trace</STRONG> were called. <STRONG>filter</STRONG>, <STRONG>initscr</STRONG>, <STRONG>new_prescr</STRONG>, <STRONG>newterm</STRONG>, <STRONG>nofilter</STRONG>, <STRONG>restartterm</STRONG>, @@ -219,49 +217,47 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These functions are not part of the X/Open Curses interface. Some - other curses implementations are known to have similar features, but + These functions are not part of the X/Open Curses interface. Some + other curses implementations are known to have similar features, but they are not compatible with <EM>ncurses</EM>: - <STRONG>o</STRONG> SVr4 provided <STRONG>traceon</STRONG> and <STRONG>traceoff</STRONG>, to control whether debugging - information was written to the "trace" file. While the functions - were always available, this feature was only enabled if <STRONG>DEBUG</STRONG> was + <STRONG>o</STRONG> SVr4 provided <STRONG>traceon</STRONG> and <STRONG>traceoff</STRONG>, to control whether debugging + information was written to the "trace" file. While the functions + were always available, this feature was only enabled if <STRONG>DEBUG</STRONG> was defined when building the library. The SVr4 tracing feature is undocumented. - <STRONG>o</STRONG> PDCurses provides <STRONG>traceon</STRONG> and <STRONG>traceoff</STRONG>, which (like SVr4) are - always available, and enable tracing to the "trace" file only when + <STRONG>o</STRONG> <EM>PDCurses</EM> provides <STRONG>traceon</STRONG> and <STRONG>traceoff</STRONG>, which (like SVr4) are + always available, and enable tracing to the "trace" file only when a debug-library is built. - PDCurses has a short description of these functions, with a note - that they are not present in X/Open Curses, <EM>ncurses</EM> or NetBSD. It - does not mention SVr4, but the functions' inclusion in a header + <EM>PDCurses</EM> has a short description of these functions, with a note + that they are not present in X/Open Curses, <EM>ncurses</EM> or NetBSD. It + does not mention SVr4, but the functions' inclusion in a header file section labeled "Quasi-standard" hints at the origin. - <STRONG>o</STRONG> NetBSD does not provide functions for enabling/disabling traces. - It uses environment variables <EM>CURSES</EM><STRONG>_</STRONG><EM>TRACE</EM><STRONG>_</STRONG><EM>MASK</EM> and - <EM>CURSES</EM><STRONG>_</STRONG><EM>TRACE</EM><STRONG>_</STRONG><EM>FILE</EM> to determine what is traced, and where the - results are written. This is available only when a debug-library + <STRONG>o</STRONG> NetBSD does not provide functions for enabling/disabling traces. + It uses environment variables <EM>CURSES</EM><STRONG>_</STRONG><EM>TRACE</EM><STRONG>_</STRONG><EM>MASK</EM> and + <EM>CURSES</EM><STRONG>_</STRONG><EM>TRACE</EM><STRONG>_</STRONG><EM>FILE</EM> to determine what is traced, and where the + results are written. This is available only when a debug-library is built. The NetBSD tracing feature is undocumented. - A few <EM>ncurses</EM> functions are not provided when symbol versioning is + A few <EM>ncurses</EM> functions are not provided when symbol versioning is used: _nc_tracebits, _tracedump, _tracemouse - The original <STRONG>trace</STRONG> routine was deprecated because it often conflicted + The original <STRONG>trace</STRONG> routine was deprecated because it often conflicted with application names. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/curs_util.3x.html b/doc/html/man/curs_util.3x.html index 6160a2cad552..f6d4ae56b77c 100644 --- a/doc/html/man/curs_util.3x.html +++ b/doc/html/man/curs_util.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_util.3x,v 1.101 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_util.3x,v 1.151 2025/11/12 01:06:36 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_util 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_util 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_util 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_util 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>delay_output</STRONG>, <STRONG>filter</STRONG>, <STRONG>flushinp</STRONG>, <STRONG>getwin</STRONG>, <STRONG>key_name</STRONG>, <STRONG>keyname</STRONG>, <STRONG>nofilter</STRONG>, <STRONG>putwin</STRONG>, <STRONG>unctrl</STRONG>, <STRONG>use_env</STRONG>, <STRONG>use_tioctl</STRONG>, <STRONG>wunctrl</STRONG> - miscellaneous <EM>curses</EM> @@ -56,72 +54,82 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*unctrl(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> - <STRONG>wchar_t</STRONG> <STRONG>*wunctrl(cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG> + <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>unctrl(chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG> + <STRONG>wchar_t</STRONG> <STRONG>*</STRONG> <STRONG>wunctrl(cchar_t</STRONG> <STRONG>*</STRONG> <EM>wch</EM><STRONG>);</STRONG> - <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*keyname(int</STRONG> <EM>c</EM><STRONG>);</STRONG> - <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*key_name(wchar_t</STRONG> <EM>wc</EM><STRONG>);</STRONG> + <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>keyname(int</STRONG> <EM>c</EM><STRONG>);</STRONG> + <STRONG>const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>key_name(wchar_t</STRONG> <EM>wc</EM><STRONG>);</STRONG> <STRONG>void</STRONG> <STRONG>filter(void);</STRONG> + <EM>/*</EM> <EM>extension</EM> <EM>*/</EM> + <STRONG>void</STRONG> <STRONG>nofilter(void);</STRONG> - <STRONG>void</STRONG> <STRONG>use_env(bool</STRONG> <EM>f</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>use_env(bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <EM>/*</EM> <EM>extension</EM> <EM>*/</EM> + <STRONG>void</STRONG> <STRONG>use_tioctl(bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>putwin(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG><EM>filep</EM><STRONG>);</STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*getwin(FILE</STRONG> <STRONG>*</STRONG><EM>filep</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>putwin(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>FILE</STRONG> <STRONG>*</STRONG> <EM>filep</EM><STRONG>);</STRONG> + <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>getwin(FILE</STRONG> <STRONG>*</STRONG> <EM>filep</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>delay_output(int</STRONG> <EM>ms</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>flushinp(void);</STRONG> - <EM>/*</EM> <EM>extensions</EM> <EM>*/</EM> - <STRONG>void</STRONG> <STRONG>nofilter(void);</STRONG> - <STRONG>void</STRONG> <STRONG>use_tioctl(bool</STRONG> <EM>f</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>flushinp(void);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> -</PRE><H3><a name="h3-unctrl">unctrl</a></H3><PRE> - The <STRONG>unctrl</STRONG> routine returns a character string which is a printable - representation of the character <EM>ch</EM>: +</PRE><H3><a name="h3-unctrl_wunctrl">unctrl, wunctrl</a></H3><PRE> + <STRONG>unctrl</STRONG> returns a null-terminated character string printably + representing the <EM>curses</EM> character <EM>ch</EM>, often one that originated in + keyboard input; see <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>. + + <STRONG>o</STRONG> Printable characters represent themselves as a one-character + string. + + <STRONG>o</STRONG> Control characters are expressed in <STRONG>^</STRONG><EM>X</EM> notation, where <EM>X</EM> is the + printable symbol of the control code's value plus 32 in the + ISO 646/"ASCII" character set. - <STRONG>o</STRONG> Printable characters are displayed as themselves, e.g., a one- - character string containing the key. + <STRONG>o</STRONG> DEL (character code 127) is represented as <STRONG>^?</STRONG>. - <STRONG>o</STRONG> Control characters are displayed in the <STRONG>^</STRONG><EM>X</EM> notation. + <STRONG>o</STRONG> A character code greater than 127 is represented in one of two + ways. - <STRONG>o</STRONG> Printing characters are displayed as is. + If the screen has not been initialized or is in meta mode (see + <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG>), it is expressed in <STRONG>M-</STRONG><EM>X</EM> notation, where X is the + representation of the code's value minus 128, as described above. - <STRONG>o</STRONG> DEL (character 127) is displayed as <STRONG>^?</STRONG>. + If the screen is not in meta mode, the character code is assumed to + represent itself. It nevertheless may not be printable; this is + the case for character codes 128-159 in ISO 8859 encodings. - <STRONG>o</STRONG> Values above 128 are either meta characters (if the screen has not - been initialized, or if <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> has been called with a <STRONG>TRUE</STRONG> - parameter), shown in the <STRONG>M-</STRONG><EM>X</EM> notation, or are displayed as - themselves. In the latter case, the values may not be printable; - this follows the X/Open specification. + <EM>ncurses</EM>'s <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG> function configures <STRONG>unctrl</STRONG>'s + handling of these character codes. - The corresponding <STRONG>wunctrl</STRONG> returns a printable representation of a - complex character <EM>wch</EM>. + <STRONG>wunctrl</STRONG> returns a null-terminated wide-character string printably + representing the <EM>curses</EM> complex character <EM>wch</EM>. - In both <STRONG>unctrl</STRONG> and <STRONG>wunctrl</STRONG> the attributes and color associated with the - character parameter are ignored. + Both functions ignore the attributes and color pair selection of their + argument. </PRE><H3><a name="h3-keyname_key_name">keyname, key_name</a></H3><PRE> The <STRONG>keyname</STRONG> routine returns a character string corresponding to the key <EM>c</EM>. Key codes are different from character codes. - <STRONG>o</STRONG> Key codes below 256 are characters. They are displayed using + <STRONG>o</STRONG> Key codes below 256 are characters. They are displayed using <STRONG>unctrl</STRONG>. - <STRONG>o</STRONG> Values above 256 may be the codes for function keys. The function + <STRONG>o</STRONG> Values above 256 may be the codes for function keys. The function key name is displayed. - <STRONG>o</STRONG> Otherwise (if there is no corresponding name and the key is not a - character) the function returns null, to denote an error. X/Open - also lists an "UNKNOWN KEY" return value, which some + <STRONG>o</STRONG> Otherwise (if there is no corresponding name and the key is not a + character) the function returns null, to denote an error. X/Open + also lists an "UNKNOWN KEY" return value, which some implementations return rather than null. - The corresponding <STRONG>key_name</STRONG> returns a multibyte character string - corresponding to the wide-character value <EM>w</EM>. The two functions + The corresponding <STRONG>key_name</STRONG> returns a multibyte character string + corresponding to the wide-character value <EM>wc</EM>. The two functions (<STRONG>keyname</STRONG> and <STRONG>key_name</STRONG>) do not return the same set of strings: <STRONG>o</STRONG> <STRONG>keyname</STRONG> returns null where <STRONG>key_name</STRONG> would display a meta character. @@ -130,7 +138,7 @@ </PRE><H3><a name="h3-filter_nofilter">filter, nofilter</a></H3><PRE> - The <STRONG>filter</STRONG> routine, if used, must be called before <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> + The <STRONG>filter</STRONG> routine, if used, must be called before <STRONG>initscr</STRONG> or <STRONG>newterm</STRONG> are called. Calling <STRONG>filter</STRONG> causes these changes in initialization: <STRONG>o</STRONG> <STRONG>LINES</STRONG> is set to 1; @@ -142,33 +150,33 @@ <STRONG>o</STRONG> and the <STRONG>home</STRONG> string is set to the value of <STRONG>cr</STRONG>. - The <STRONG>nofilter</STRONG> routine cancels the effect of a preceding <STRONG>filter</STRONG> call. - That allows the caller to initialize a screen on a different device, - using a different value of <STRONG>$TERM</STRONG>. The limitation arises because the + The <STRONG>nofilter</STRONG> routine cancels the effect of a preceding <STRONG>filter</STRONG> call. + That allows the caller to initialize a screen on a different device, + using a different value of <STRONG>$TERM</STRONG>. The limitation arises because the <STRONG>filter</STRONG> routine modifies the in-memory copy of the terminal information. </PRE><H3><a name="h3-use_env">use_env</a></H3><PRE> - The <STRONG>use_env</STRONG> routine, if used, should be called before <STRONG>initscr</STRONG> or - <STRONG>newterm</STRONG> are called (because those compute the screen size). It - modifies the way <EM>ncurses</EM> treats environment variables when determining + The <STRONG>use_env</STRONG> routine, if used, should be called before <STRONG>initscr</STRONG> or + <STRONG>newterm</STRONG> are called (because those compute the screen size). It + modifies the way <EM>ncurses</EM> treats environment variables when determining the screen size. - <STRONG>o</STRONG> Normally <EM>ncurses</EM> looks first at the terminal database for the + <STRONG>o</STRONG> Normally <EM>ncurses</EM> looks first at the terminal database for the screen size. - If <STRONG>use_env</STRONG> was called with <STRONG>FALSE</STRONG> for parameter, it stops here + If <STRONG>use_env</STRONG> was called with <STRONG>FALSE</STRONG> for parameter, it stops here unless <STRONG>use_tioctl</STRONG> was also called with <STRONG>TRUE</STRONG> for parameter. - <STRONG>o</STRONG> Then it asks for the screen size via operating system calls. If + <STRONG>o</STRONG> Then it asks for the screen size via operating system calls. If successful, it overrides the values from the terminal database. - <STRONG>o</STRONG> Finally (unless <STRONG>use_env</STRONG> was called with <STRONG>FALSE</STRONG> parameter), <EM>ncurses</EM> - examines the <EM>LINES</EM> or <EM>COLUMNS</EM> environment variables, using a value - in those to override the results from the operating system or + <STRONG>o</STRONG> Finally (unless <STRONG>use_env</STRONG> was called with <STRONG>FALSE</STRONG> parameter), <EM>ncurses</EM> + examines the <EM>LINES</EM> or <EM>COLUMNS</EM> environment variables, using a value + in those to override the results from the operating system or terminal database. - <EM>curses</EM> also updates the screen size in response to <STRONG>SIGWINCH</STRONG>, unless + <EM>curses</EM> also updates the screen size in response to <EM>SIGWINCH</EM>, unless overridden by the <EM>LINES</EM> or <EM>COLUMNS</EM> environment variables, @@ -178,94 +186,99 @@ <STRONG>use_tioctl</STRONG> is called with <STRONG>TRUE</STRONG> as an argument, <EM>ncurses</EM> modifies the last step in its computation of screen size as follows: - <STRONG>o</STRONG> checks if the <EM>LINES</EM> and <EM>COLUMNS</EM> environment variables are set to a - number greater than zero. + <STRONG>o</STRONG> checks whether the <EM>LINES</EM> and <EM>COLUMNS</EM> environment variables are set + to a number greater than zero. <STRONG>o</STRONG> for each, <EM>ncurses</EM> updates the corresponding environment variable with the value that it has obtained via operating system call or from the terminal database. <STRONG>o</STRONG> <EM>ncurses</EM> re-fetches the value of the environment variables so that - it is still the environment variables which set the screen size. + it is still the environment variables that set the screen size. The <STRONG>use_env</STRONG> and <STRONG>use_tioctl</STRONG> routines combine as follows. <STRONG>use_env</STRONG> <STRONG>use_tioctl</STRONG> <STRONG>Summary</STRONG> ----------------------------------------------------------------- - <STRONG>TRUE</STRONG> <STRONG>FALSE</STRONG> This is the default behavior. <EM>ncurses</EM> - uses operating system calls unless - overridden by <EM>LINES</EM> or <EM>COLUMNS</EM> + <STRONG>TRUE</STRONG> <STRONG>FALSE</STRONG> <EM>ncurses</EM> uses operating system calls + unless overridden by <EM>LINES</EM> or <EM>COLUMNS</EM> environment variables; default. - <STRONG>TRUE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> updates <EM>LINES</EM> and <EM>COLUMNS</EM> based + <STRONG>TRUE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> updates <EM>LINES</EM> and <EM>COLUMNS</EM> based on operating system calls. - <STRONG>FALSE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> ignores <EM>LINES</EM> and <EM>COLUMNS</EM>, using + <STRONG>FALSE</STRONG> <STRONG>TRUE</STRONG> <EM>ncurses</EM> ignores <EM>LINES</EM> and <EM>COLUMNS</EM>, using operating system calls to obtain size. </PRE><H3><a name="h3-putwin_getwin">putwin, getwin</a></H3><PRE> - The <STRONG>putwin</STRONG> routine writes all data associated with window (or pad) <EM>win</EM> - into the file to which <EM>filep</EM> points. This information can be later + The <STRONG>putwin</STRONG> routine writes all data associated with window (or pad) <EM>win</EM> + into the file to which <EM>filep</EM> points. This information can be later retrieved using the <STRONG>getwin</STRONG> function. - The <STRONG>getwin</STRONG> routine reads window related data stored in the file by - <STRONG>putwin</STRONG>. The routine then creates and initializes a new window using - that data. It returns a pointer to the new window. There are a few + The <STRONG>getwin</STRONG> routine reads window related data stored in the file by + <STRONG>putwin</STRONG>. The routine then creates and initializes a new window using + that data. It returns a pointer to the new window. There are a few caveats: - <STRONG>o</STRONG> the data written is a copy of the <EM>WINDOW</EM> structure, and its - associated character cells. The format differs between the wide- - character (<EM>ncursesw</EM>) and non-wide (<EM>ncurses</EM>) libraries. You can + <STRONG>o</STRONG> the data written is a copy of the <EM>WINDOW</EM> structure, and its + associated character cells. The format differs between the wide- + character (<EM>ncursesw</EM>) and non-wide (<EM>ncurses</EM>) libraries. You can transfer data between the two, however. - <STRONG>o</STRONG> the retrieved window is always created as a top-level window (or + <STRONG>o</STRONG> the retrieved window is always created as a top-level window (or pad), rather than a subwindow. - <STRONG>o</STRONG> the window's character cells contain the color pair <EM>value</EM>, but not - the actual color <EM>numbers</EM>. If cells in the retrieved window use - color pairs which have not been created in the application using + <STRONG>o</STRONG> the window's character cells contain the color pair <EM>value</EM>, but not + the actual color <EM>numbers</EM>. If cells in the retrieved window use + color pairs that have not been created in the application using <STRONG>init_pair</STRONG>, they will not be colored when the window is refreshed. </PRE><H3><a name="h3-delay_output">delay_output</a></H3><PRE> - The <STRONG>delay_output</STRONG> routine inserts an <EM>ms</EM> millisecond pause in output. - Employ this function judiciously when terminal output uses padding, - because <EM>ncurses</EM> transmits null characters (consuming CPU and I/O - resources) instead of sleeping and requesting resumption from the + The <STRONG>delay_output</STRONG> routine inserts an <EM>ms</EM> millisecond pause in output. + Employ this function judiciously when terminal output uses padding, + because <EM>ncurses</EM> transmits null characters (consuming CPU and I/O + resources) instead of sleeping and requesting resumption from the operating system. Padding is used unless: <STRONG>o</STRONG> the terminal description has <STRONG>npc</STRONG> (<STRONG>no_pad_char</STRONG>) capability, or <STRONG>o</STRONG> the environment variable <STRONG>NCURSES_NO_PADDING</STRONG> is set. - If padding is not in use, <EM>ncurses</EM> uses <STRONG>napms</STRONG> to perform the delay. If - the value of <EM>ms</EM> exceeds 30,000 (thirty seconds), it is capped at that + If padding is not in use, <EM>ncurses</EM> uses <STRONG>napms</STRONG> to perform the delay. If + the value of <EM>ms</EM> exceeds 30,000 (thirty seconds), it is capped at that value. </PRE><H3><a name="h3-flushinp">flushinp</a></H3><PRE> - The <STRONG>flushinp</STRONG> routine throws away any typeahead that has been typed by + The <STRONG>flushinp</STRONG> routine throws away any typeahead that has been typed by the user and has not yet been read by the program. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Except for <STRONG>flushinp</STRONG>, routines that return an integer return <STRONG>ERR</STRONG> upon - failure and <STRONG>OK</STRONG> (SVr4 specifies only "an integer value other than <STRONG>ERR</STRONG>") - upon successful completion. + Except for <STRONG>flushinp</STRONG>, functions that return integers return <STRONG>ERR</STRONG> upon + failure and <STRONG>OK</STRONG> upon success. - Routines that return pointers return <STRONG>NULL</STRONG> on error. + Functions that return pointers return a null pointer on failure. - X/Open Curses does not specify any error conditions. In this - implementation + In <EM>ncurses</EM>, - <STRONG>flushinp</STRONG> - returns an error if the terminal was not initialized. + <STRONG>o</STRONG> <STRONG>flushinp</STRONG> returns <STRONG>ERR</STRONG> if the terminal was not initialized, and - <STRONG>putwin</STRONG> - returns an error if the associated <STRONG>fwrite</STRONG> calls return an - error. + <STRONG>o</STRONG> <STRONG>putwin</STRONG> returns <STRONG>ERR</STRONG> if its associated <STRONG>write(2)</STRONG> calls return <STRONG>ERR</STRONG>. + + +</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> + <STRONG>wunctrl</STRONG> is part of <EM>ncurses</EM>'s wide-character API, and is not available + in its non-wide-character configuration. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. + + SVr4 describes a successful return value only as "an integer value + other than <EM>ERR</EM>". + </PRE><H3><a name="h3-filter">filter</a></H3><PRE> The SVr4 documentation describes the action of <STRONG>filter</STRONG> only in the @@ -277,9 +290,9 @@ The limitation to 30 seconds and the use of <STRONG>napms</STRONG> differ from other implementations. - <STRONG>o</STRONG> SVr4 curses does not delay if no padding character is available. + <STRONG>o</STRONG> SVr4 <EM>curses</EM> does not delay if no padding character is available. - <STRONG>o</STRONG> NetBSD curses uses <STRONG>napms</STRONG> when no padding character is available, + <STRONG>o</STRONG> NetBSD <EM>curses</EM> uses <STRONG>napms</STRONG> when no padding character is available, but does not take timing into account when using the padding character. @@ -288,57 +301,58 @@ </PRE><H3><a name="h3-keyname">keyname</a></H3><PRE> The <STRONG>keyname</STRONG> function may return the names of user-defined string - capabilities which are defined in the terminfo entry via the <STRONG>-x</STRONG> option - of <STRONG>tic</STRONG>. This implementation automatically assigns at run-time keycodes - to user-defined strings which begin with "k". The keycodes start at - KEY_MAX, but are not guaranteed to be the same value for different runs - because user-defined codes are merged from all terminal descriptions - which have been loaded. The <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG> function controls - whether this data is loaded when the terminal description is read by - the library. + capabilities that are defined in the terminfo entry via the <STRONG>-x</STRONG> option + of <STRONG>tic</STRONG>. This implementation automatically assigns at run-time key + codes to user-defined strings that begin with "k". The key codes start + at KEY_MAX, but are not guaranteed to be the same value for different + runs because user-defined codes are merged from all terminal + descriptions that have been loaded. The <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG> + function controls whether this data is loaded when the terminal + description is read by the library. </PRE><H3><a name="h3-nofilter_use_tioctl">nofilter, use_tioctl</a></H3><PRE> - The <STRONG>nofilter</STRONG> and <STRONG>use_tioctl</STRONG> routines are specific to <EM>ncurses</EM>. They - were not supported on Version 7, BSD or System V implementations. It - is recommended that any code depending on <EM>ncurses</EM> extensions be + The <STRONG>nofilter</STRONG> and <STRONG>use_tioctl</STRONG> routines are specific to <EM>ncurses</EM>. They + were not supported on Version 7, BSD or System V implementations. It + is recommended that any code depending on <EM>ncurses</EM> extensions be conditioned using <STRONG>NCURSES_VERSION</STRONG>. </PRE><H3><a name="h3-putwin_getwin-file-format">putwin/getwin file-format</a></H3><PRE> The <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG> functions have several issues with portability: - <STRONG>o</STRONG> The files written and read by these functions use an - implementation-specific format. Although the format is an obvious + <STRONG>o</STRONG> The files written and read by these functions use an + implementation-specific format. Although the format is an obvious target for standardization, it has been overlooked. - Interestingly enough, according to the copyright dates in Solaris - source, the functions (along with <STRONG>scr_init</STRONG>, etc.) originated with + Interestingly enough, according to the copyright dates in Solaris + source, the functions (along with <STRONG>scr_init</STRONG>, etc.) originated with the University of California, Berkeley (in 1982) and were later (in 1988) incorporated into SVr4. Oddly, there are no such functions - in the 4.3BSD curses sources. + in the 4.3BSD <EM>curses</EM> sources. <STRONG>o</STRONG> Most implementations simply dump the binary <EM>WINDOW</EM> structure to the - file. These include SVr4 curses, NetBSD and PDCurses, as well as - older <EM>ncurses</EM> versions. This implementation (as well as the X/Open - variant of Solaris curses, dated 1995) uses textual dumps. + file. These include SVr4 <EM>curses</EM>, NetBSD <EM>curses</EM>, and <EM>PDCurses</EM>, as + well as older <EM>ncurses</EM> versions. This implementation (as well as + <EM>xcurses</EM>, the X/Open variant of Solaris <EM>curses</EM>, dated 1995) uses + textual dumps. - The implementations which use binary dumps use block-I/O (the - <STRONG>fwrite</STRONG> and <STRONG>fread</STRONG> functions). Those that use textual dumps use - buffered-I/O. A few applications may happen to write extra data in - the file using these functions. Doing that can run into problems - mixing block- and buffered-I/O. This implementation reduces the - problem on writes by flushing the output. However, reading from a - file written using mixed schemes may not be successful. + The implementations that use binary dumps use block I/O (<STRONG>write(2)</STRONG> + and <STRONG>read(2)</STRONG> functions). Those that use textual dumps use buffered + I/O. A few applications may happen to write extra data in the file + using these functions. Doing that can run into problems mixing + block and buffered I/O. This implementation reduces the problem on + writes by flushing the output. However, reading from a file + written using mixed schemes may not be successful. </PRE><H3><a name="h3-unctrl_wunctrl">unctrl, wunctrl</a></H3><PRE> - X/Open Curses, Issue 4 describes these functions. It states that - <STRONG>unctrl</STRONG> and <STRONG>wunctrl</STRONG> will return a null pointer if unsuccessful, but does - not define any error conditions. This implementation checks for three + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for them. It states that <STRONG>unctrl</STRONG> and <STRONG>wunctrl</STRONG> will return a + null pointer if unsuccessful. This implementation checks for three cases: - <STRONG>o</STRONG> the parameter is a 7-bit US-ASCII code. This is the case that + <STRONG>o</STRONG> the parameter is a 7-bit US-ASCII code. This is the case that X/Open Curses documented. <STRONG>o</STRONG> the parameter is in the range 128-159, i.e., a C1 control code. If @@ -348,7 +362,7 @@ "~A", etc., analogous to "^@", "^A", C0 controls. X/Open Curses does not document whether <STRONG>unctrl</STRONG> can be called before - initializing curses. This implementation permits that, and returns + initializing <EM>curses</EM>. This implementation permits that, and returns the "~@", etc., values in that case. <STRONG>o</STRONG> parameter values outside the 0 to 255 range. <STRONG>unctrl</STRONG> returns a null @@ -367,32 +381,46 @@ Likewise, the <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> function allows the caller to change the output of <STRONG>keyname</STRONG>, i.e., it determines whether to use the "M-" prefix for "meta" keys (codes in the range 128 to 255). Both - <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG> and <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> succeed only after curses is + <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG> and <STRONG><A HREF="curs_inopts.3x.html">meta(3x)</A></STRONG> succeed only after <EM>curses</EM> is initialized. X/Open Curses does not document the treatment of codes 128 to 159. When treating them as "meta" keys (or if <STRONG>keyname</STRONG> is called - before initializing curses), this implementation returns strings + before initializing <EM>curses</EM>), this implementation returns strings "M-^@", "M-^A", etc. - X/Open Curses documents <STRONG>unctrl</STRONG> as declared in <STRONG><unctrl.h></STRONG>, which <EM>ncurses</EM> - does. However, <EM>ncurses</EM>' <STRONG><curses.h></STRONG> includes <STRONG><unctrl.h></STRONG>, matching the - behavior of SVr4 curses. Other implementations may not do that. + X/Open Curses documents <EM>unctrl</EM> as declared in <EM>unctrl.h</EM>, which <EM>ncurses</EM> + does. However, <EM>ncurses</EM>'s <EM>curses.h</EM> includes <EM>unctrl.h</EM>, matching the + behavior of SVr4 <EM>curses</EM>. Other implementations may not do that. </PRE><H3><a name="h3-use_env_use_tioctl">use_env, use_tioctl</a></H3><PRE> - If <EM>ncurses</EM> is configured to provide the sp-functions extension, the - state of <STRONG>use_env</STRONG> and <STRONG>use_tioctl</STRONG> may be updated before creating each - <EM>screen</EM> rather than once only (<STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>). This feature of - <STRONG>use_env</STRONG> is not provided by other implementations of curses. + If <EM>ncurses</EM> is configured to provide the sp-functions extension, the + state of <STRONG>use_env</STRONG> and <STRONG>use_tioctl</STRONG> may be updated before creating each + <EM>screen</EM> rather than once only (<STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>). This feature of + <STRONG>use_env</STRONG> is not provided by other implementations of <EM>curses</EM>. -</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, - <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>, <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, - <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG> +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + 4BSD (1980) introduced <EM>unctrl</EM>, defining it as a macro in <EM>unctrl.h</EM>. + + SVr2 (1984) added <EM>delay</EM><STRONG>_</STRONG><EM>output</EM>, <EM>flushinp</EM>, and <EM>keyname</EM>. + + SVr3 (1987) supplied <EM>filter</EM>. Later that year, SVr3.1 brought <EM>getwin</EM> + and <EM>putwin</EM>, reading and writing window dumps with <STRONG>fread(3)</STRONG> and + <STRONG>fwrite(3)</STRONG>, respectively. + + SVr4 (1989) furnished <EM>use</EM><STRONG>_</STRONG><EM>env</EM>. + X/Open Curses Issue 4 (1995) specified <EM>key</EM><STRONG>_</STRONG><EM>name</EM> and <EM>wunctrl</EM>. + <EM>ncurses</EM> 5.6 (2006) added <EM>nofilter</EM>, and 6.0 (2015) <EM>use</EM><STRONG>_</STRONG><EM>tioctl</EM>. -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> + +</PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG>, <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, + <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>, <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, + <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG> + +ncurses 6.6 2025-11-11 <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -400,7 +428,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a> <ul> -<li><a href="#h3-unctrl">unctrl</a></li> +<li><a href="#h3-unctrl_wunctrl">unctrl, wunctrl</a></li> <li><a href="#h3-keyname_key_name">keyname, key_name</a></li> <li><a href="#h3-filter_nofilter">filter, nofilter</a></li> <li><a href="#h3-use_env">use_env</a></li> @@ -411,6 +439,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF </ul> </li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> +<li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a> <ul> <li><a href="#h3-filter">filter</a></li> @@ -422,6 +451,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF <li><a href="#h3-use_env_use_tioctl">use_env, use_tioctl</a></li> </ul> </li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/curs_variables.3x.html b/doc/html/man/curs_variables.3x.html index 92ae9851fdf2..f9b033e76d85 100644 --- a/doc/html/man/curs_variables.3x.html +++ b/doc/html/man/curs_variables.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2010-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,29 +27,27 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_variables.3x,v 1.47 2024/04/13 22:37:35 tom Exp @ + * @Id: curs_variables.3x,v 1.73 2025/08/23 23:02:32 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_variables 3x 2024-04-13 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_variables 3x 2025-08-23 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_variables 3x 2024-04-13 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_variables 3x 2025-08-23 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <EM>bool</EM>, <EM>chtype</EM>, <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>, <EM>attr</EM><STRONG>_</STRONG><EM>t</EM>, <EM>SCREEN</EM>, <EM>WINDOW</EM>, <STRONG>TRUE</STRONG>, <STRONG>FALSE</STRONG>, <STRONG>ERR</STRONG>, <STRONG>OK</STRONG>, - <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>, <STRONG>stdscr</STRONG>, <STRONG>COLORS</STRONG>, <STRONG>COLOR_PAIRS</STRONG>, <STRONG>COLS</STRONG>, <STRONG>LINES</STRONG>, <STRONG>ESCDELAY</STRONG>, - <STRONG>TABSIZE</STRONG> - <EM>curses</EM> data types, constants, and global variables + <STRONG>CCHARW_MAX</STRONG>, <STRONG>curscr</STRONG>, <STRONG>newscr</STRONG>, <STRONG>stdscr</STRONG>, <STRONG>COLORS</STRONG>, <STRONG>COLOR_PAIRS</STRONG>, <STRONG>COLS</STRONG>, <STRONG>LINES</STRONG>, + <STRONG>ESCDELAY</STRONG>, <STRONG>TABSIZE</STRONG> - <EM>curses</EM> data types, constants, and global variables </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> @@ -70,6 +68,9 @@ <STRONG>const</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>ERR;</STRONG> <STRONG>const</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>OK;</STRONG> + <EM>/*</EM> <EM>extension</EM> <EM>*/</EM> + <STRONG>const</STRONG> <EM>/*</EM> <STRONG>...</STRONG> <EM>*/</EM> <STRONG>CCHARW_MAX;</STRONG> + <EM>/*</EM> <EM>variables</EM> <EM>*/</EM> <STRONG>int</STRONG> <STRONG>COLORS;</STRONG> <STRONG>int</STRONG> <STRONG>COLOR_PAIRS;</STRONG> @@ -103,19 +104,25 @@ </PRE><H3><a name="h3-ERR_OK">ERR, OK</a></H3><PRE> - <EM>curses</EM> and <EM>terminfo</EM> routines frequently return these constant integral + <EM>curses</EM> and <EM>terminfo</EM> functions frequently return these constant integral values indicating failure and success, respectively. -</PRE><H2><a name="h2-PREDEFINED-TYPES">PREDEFINED TYPES</a></H2><PRE> +</PRE><H3><a name="h3-CCHARW_MAX">CCHARW_MAX</a></H3><PRE> + This integral value, an <EM>ncurses</EM> extension, indicates the maximum number + of <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> wide characters that can be stored in a <EM>curses</EM> complex + character <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. + + +</PRE><H2><a name="h2-DATA-TYPES">DATA TYPES</a></H2><PRE> </PRE><H3><a name="h3-bool"><EM>bool</EM></a></H3><PRE> - X/Open Issue 4 <EM>curses</EM> (1996) preceded the ISO C99 and ISO C++98 - standards, each of which also defined a Boolean data type. The <EM>curses</EM> - library requires an integral type <EM>bool</EM>. + <EM>curses</EM> defines an integral type <EM>bool</EM>. X/Open Issue 4 <EM>curses</EM> (1996) + preceded the ISO C99 and ISO C++98 standards, each of which also + defined a Boolean data type of the same name. - <STRONG>ncurses</STRONG>' configure script attempts to discover the data type used by - the system's C and C++ compilers, to reuse for the <EM>curses</EM> <EM>bool</EM>. + <EM>ncurses</EM>'s configure script attempts to discover the data type used by + the system's C and C++ compilers, to reuse them as its own <EM>bool</EM>. </PRE><H3><a name="h3-chtype"><EM>chtype</EM></a></H3><PRE> @@ -147,48 +154,52 @@ </PRE><H2><a name="h2-VARIABLES">VARIABLES</a></H2><PRE> -</PRE><H3><a name="h3-curscr_stdscr_newscr">curscr, stdscr, newscr</a></H3><PRE> - The library records updates to the terminal screen in a window named - <STRONG>curscr</STRONG>. This object is referred to as the "physical screen" in +</PRE><H3><a name="h3-curscr_newscr_stdscr">curscr, newscr, stdscr</a></H3><PRE> + When a <EM>curses</EM> application calls <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>, the library + creates a window named <STRONG>stdscr</STRONG> that is the same size as the terminal + screen, (minus any lines reserved by <STRONG><A HREF="curs_kernel.3x.html">ripoffline(3x)</A></STRONG> or <STRONG><A HREF="curs_slk.3x.html">slk_init(3x)</A></STRONG>) + and is the implicit window used by functions that interact with a + window but do not take a parameter identifying one; many <EM>curses</EM> + functions use it. An application need not use <STRONG>stdscr</STRONG>; it might prefer + to tile the display into multiple windows instead. + + The library records updates to the terminal screen in a window named + <STRONG>curscr</STRONG>. This object is referred to as the "physical screen" in <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> and <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>. - <EM>ncurses</EM> collects pending updates to the terminal screen in a window - named <STRONG>newscr</STRONG>. This object is referred to as the "virtual screen" in - the <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, and <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>. When the - screen is refreshed, <EM>curses</EM> determines a minimal set of updates using + <EM>ncurses</EM> collects pending updates to the terminal screen in a window + named <STRONG>newscr</STRONG>. This object is referred to as the "virtual screen" in + the <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, and <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG>. When the + screen is refreshed, <EM>curses</EM> determines a minimal set of updates using the terminal's capabilities to make <STRONG>curscr</STRONG> look like <STRONG>newscr</STRONG>. - Once <EM>curses</EM> is initialized, it creates a window named <STRONG>stdscr</STRONG>. It is - the same size as the terminal screen and is the default window used by - routines that do not take a parameter identifying one. Many <EM>curses</EM> - functions use this window. - </PRE><H3><a name="h3-COLORS">COLORS</a></H3><PRE> - Once <EM>curses</EM> is initialized, <STRONG>COLORS</STRONG> contains the number of colors - supported by the terminal; see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>. + Once a <EM>curses</EM> screen is initialized, <STRONG>COLORS</STRONG> contains the number of + colors supported by the terminal; see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>. </PRE><H3><a name="h3-COLOR_PAIRS">COLOR_PAIRS</a></H3><PRE> - Once <EM>curses</EM> is initialized, <STRONG>COLOR_PAIRS</STRONG> contains the number of color - pairs supported by the terminal; see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>. + Once a <EM>curses</EM> screen is initialized, <STRONG>COLOR_PAIRS</STRONG> contains the number of + color pairs supported by the terminal; see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>. </PRE><H3><a name="h3-COLS_LINES">COLS, LINES</a></H3><PRE> - Once <EM>curses</EM> is initialized, <STRONG>COLS</STRONG> and <STRONG>LINES</STRONG> contain the screen's width - and height in character cells, respectively; that is, the number of + Once a <EM>curses</EM> screen is initialized, <STRONG>COLS</STRONG> and <STRONG>LINES</STRONG> contain its width + and height in character cells, respectively; that is, the number of columns and lines. </PRE><H3><a name="h3-ESCDELAY">ESCDELAY</a></H3><PRE> - For <EM>curses</EM> to distinguish the ESC character resulting from a user's - press of the "Escape" key on the input device from one beginning an - <EM>escape</EM> <EM>sequence</EM> (as commonly produced by function keys), it waits after - the escape character to see if further characters are available on the + When reading key strokes from a window in keypad mode, <EM>curses</EM> + distinguishes the ESC character resulting from a user's press of the + "Escape" key on the input device from one beginning an escape sequence + (commonly produced by function keys), by waiting after receiving the + escape character to see if further characters are available on the input stream within a short interval. <STRONG>ESCDELAY</STRONG> stores this interval in milliseconds. - If <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> is disabled for the <EM>curses</EM> window receiving input, a + If <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> is disabled for the <EM>curses</EM> window receiving input, a program must disambiguate escape sequences itself. @@ -198,15 +209,24 @@ </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - Either <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> initializes <EM>curses</EM>. + Initialize a <EM>curses</EM> screen with either <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>. If <EM>ncurses</EM> is configured to provide separate <EM>curses</EM> and <EM>tinfo</EM> - libraries, most of these variables reside in the former. + libraries, most of these symbols reside in the former. Both use the + <STRONG>bool</STRONG> data type. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + The <STRONG>CCHARW_MAX</STRONG> constant, and <STRONG>ESCDELAY</STRONG>, <STRONG>TABSIZE</STRONG>, and <STRONG>newscr</STRONG> variables, + are extensions, the first of these originating in <EM>ncurses</EM>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + The X/Open Curses standard documents all of the foregoing types and - symbols except for <STRONG>newscr</STRONG>, <STRONG>TABSIZE</STRONG>, and <STRONG>ESCDELAY</STRONG>. + symbols except for <STRONG>CCHARW_MAX</STRONG>, <STRONG>newscr</STRONG>, <STRONG>TABSIZE</STRONG>, and <STRONG>ESCDELAY</STRONG>. X/Open Curses describes <STRONG>curscr</STRONG> only as "an internal data structure"; SVr4 gave more details, noting its use "for certain low-level @@ -214,59 +234,58 @@ Neither specified its interaction with the rest of the interface beyond use as an argument to <STRONG><A HREF="curs_outopts.3x.html">clearok(3x)</A></STRONG> and <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>. - <STRONG>newscr</STRONG> is a feature of SVr4 <EM>curses</EM>. When refreshing the screen, it is - used as a working area for combining the standard window <STRONG>stdscr</STRONG> with - any others the application may have created with <STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>. When the + <STRONG>newscr</STRONG> is a feature of SVr4 <EM>curses</EM>. When refreshing the screen, it is + used as a working area for combining the standard window <STRONG>stdscr</STRONG> with + any others the application may have created with <STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>. When the update of <STRONG>newscr</STRONG> is complete, <EM>curses</EM> modifies <STRONG>curscr</STRONG> to match <STRONG>newscr</STRONG>. <STRONG>TABSIZE</STRONG> is a feature of SVr4 <EM>curses</EM>. - <STRONG>o</STRONG> SVr4 initially sets <STRONG>TABSIZE</STRONG> from the terminal description's - <STRONG>init_tabs</STRONG> capability. After that, it can be altered by + <STRONG>o</STRONG> SVr4 initially sets <STRONG>TABSIZE</STRONG> from the terminal description's + <STRONG>init_tabs</STRONG> (<STRONG>it</STRONG>) capability. After that, it can be altered by applications using SVr4 <EM>curses</EM>. - <STRONG>o</STRONG> SVr4 <EM>curses</EM> uses the value of <STRONG>TABSIZE</STRONG> to compute the position of - tab stops when updating both the virtual screen with <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG> and - the physical screen with <STRONG><A HREF="curs_terminfo.3x.html">mvcur(3x)</A></STRONG>. + <STRONG>o</STRONG> SVr4 <EM>curses</EM> uses <STRONG>TABSIZE</STRONG>'s value to compute the position of tab + stops when updating both the virtual screen with <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG> and the + physical screen with <STRONG><A HREF="curs_terminfo.3x.html">mvcur(3x)</A></STRONG>. - <STRONG>o</STRONG> <EM>ncurses</EM> uses the value of <STRONG>TABSIZE</STRONG> only to update the virtual - screen. It uses the terminal description's "<STRONG>it</STRONG>" (<STRONG>init_tabs</STRONG>) - capability for computing hardware tabs (that is, tab stops on the + <STRONG>o</STRONG> In <EM>ncurses</EM>, <STRONG>TABSIZE</STRONG>'s value affects only the virtual screen. The + library uses the terminal type description's <STRONG>init_tabs</STRONG> (<STRONG>it</STRONG>) + capability to compute hardware tabs (that is, tab stops on the physical screen). - <STRONG>o</STRONG> Other implementations differ. For instance, NetBSD <EM>curses</EM> allows - <STRONG>TABSIZE</STRONG> to be set through an environment variable. <EM>ncurses</EM> does + <STRONG>o</STRONG> Other implementations differ. For instance, NetBSD <EM>curses</EM> allows + <STRONG>TABSIZE</STRONG> to be set through an environment variable. <EM>ncurses</EM> does not. NetBSD <EM>curses</EM> does not support hardware tabs; it uses the <STRONG>init_tabs</STRONG> - capability and the <STRONG>TABSIZE</STRONG> variable only for updating the virtual + (<STRONG>it</STRONG>) capability and the <STRONG>TABSIZE</STRONG> variable only to update the virtual screen. <STRONG>ESCDELAY</STRONG> is a feature of AIX <EM>curses</EM>. - <STRONG>o</STRONG> In AIX, the units for <STRONG>ESCDELAY</STRONG> are <EM>fifths</EM> of milliseconds. + <STRONG>o</STRONG> AIX treats <STRONG>ESCDELAY</STRONG>'s value as counting <EM>fifths</EM> of milliseconds. - <STRONG>o</STRONG> The default value for AIX's <STRONG>ESCDELAY</STRONG> equals 0.1 seconds. + <STRONG>o</STRONG> AIX's default <STRONG>ESCDELAY</STRONG> equals 0.1 seconds. - <STRONG>o</STRONG> AIX also enforces a limit of 10,000 seconds for <STRONG>ESCDELAY</STRONG>; <EM>ncurses</EM> - does not enforce any upper limit. + <STRONG>o</STRONG> AIX also enforces a limit of 10,000 seconds for <STRONG>ESCDELAY</STRONG>; <EM>ncurses</EM> + does not enforce an upper limit. - <EM>ncurses</EM> has long used <STRONG>ESCDELAY</STRONG> with units of milliseconds, making it - impossible to be completely compatible with AIX. Consequently, most - users have decided either to override the value, or to rely upon its - default. + <EM>ncurses</EM> has long interpreted <STRONG>ESCDELAY</STRONG> as a count of milliseconds, + making it impossible to be completely compatible with AIX. + Consequently, most users have decided either to override the value, or + to rely upon its default. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>, <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, - <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - [UAX #29] "Unicode Standard Annex #29: Unicode Text Segmentation"; - <https://unicode.org/reports/tr29/> + [UAX #29] "Unicode Standard Annex #29: Unicode Text Segmentation" + <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG> further discusses the <EM>ncurses</EM> extension <STRONG>CCHARW_MAX</STRONG>. + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG>, <STRONG><A HREF="curs_opaque.3x.html">curs_opaque(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, + <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> -ncurses 6.5 2024-04-13 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> +ncurses 6.6 2025-08-23 <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -277,9 +296,10 @@ ncurses 6.5 2024-04-13 <STRONG><A HREF="cur <ul> <li><a href="#h3-TRUE_FALSE">TRUE, FALSE</a></li> <li><a href="#h3-ERR_OK">ERR, OK</a></li> +<li><a href="#h3-CCHARW_MAX">CCHARW_MAX</a></li> </ul> </li> -<li><a href="#h2-PREDEFINED-TYPES">PREDEFINED TYPES</a> +<li><a href="#h2-DATA-TYPES">DATA TYPES</a> <ul> <li><a href="#h3-bool">bool</a></li> <li><a href="#h3-chtype">chtype</a></li> @@ -290,7 +310,7 @@ ncurses 6.5 2024-04-13 <STRONG><A HREF="cur </li> <li><a href="#h2-VARIABLES">VARIABLES</a> <ul> -<li><a href="#h3-curscr_stdscr_newscr">curscr, stdscr, newscr</a></li> +<li><a href="#h3-curscr_newscr_stdscr">curscr, newscr, stdscr</a></li> <li><a href="#h3-COLORS">COLORS</a></li> <li><a href="#h3-COLOR_PAIRS">COLOR_PAIRS</a></li> <li><a href="#h3-COLS_LINES">COLS, LINES</a></li> @@ -299,6 +319,7 @@ ncurses 6.5 2024-04-13 <STRONG><A HREF="cur </ul> </li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> diff --git a/doc/html/man/curs_window.3x.html b/doc/html/man/curs_window.3x.html index ea99659ecf62..3f5274efc16b 100644 --- a/doc/html/man/curs_window.3x.html +++ b/doc/html/man/curs_window.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2020-2023,2024 Thomas E. Dickey * + * Copyright 2020-2024,2025 Thomas E. Dickey * * Copyright 1998-2015,2016 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: curs_window.3x,v 1.48 2024/04/20 21:20:07 tom Exp @ + * @Id: curs_window.3x,v 1.71 2025/08/23 22:50:00 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>curs_window 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>curs_window 3x 2025-08-23 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">curs_window 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">curs_window 3x 2025-08-23 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG> Library calls <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>newwin</STRONG>, <STRONG>delwin</STRONG>, <STRONG>mvwin</STRONG>, <STRONG>subwin</STRONG>, <STRONG>derwin</STRONG>, <STRONG>mvderwin</STRONG>, <STRONG>dupwin</STRONG>, <STRONG>wsyncup</STRONG>, <STRONG>syncok</STRONG>, <STRONG>wcursyncup</STRONG>, <STRONG>wsyncdown</STRONG> - create and manipulate <EM>curses</EM> windows @@ -54,23 +52,23 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*newwin(</STRONG> - <STRONG>int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>,</STRONG> - <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>delwin(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvwin(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*subwin(WINDOW</STRONG> <STRONG>*</STRONG><EM>orig</EM><STRONG>,</STRONG> - <STRONG>int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>,</STRONG> - <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*derwin(WINDOW</STRONG> <STRONG>*</STRONG><EM>orig</EM><STRONG>,</STRONG> - <STRONG>int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>,</STRONG> - <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>mvderwin(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>par</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>par</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG> - <STRONG>WINDOW</STRONG> <STRONG>*dupwin(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>wsyncup(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> - <STRONG>int</STRONG> <STRONG>syncok(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>wcursyncup(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> - <STRONG>void</STRONG> <STRONG>wsyncdown(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>);</STRONG> + <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>newwin(</STRONG> + <STRONG>int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>,</STRONG> + <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>delwin(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvwin(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>x</EM><STRONG>);</STRONG> + <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>subwin(WINDOW</STRONG> <STRONG>*</STRONG> <EM>orig</EM><STRONG>,</STRONG> + <STRONG>int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>,</STRONG> + <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG> + <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>derwin(WINDOW</STRONG> <STRONG>*</STRONG> <EM>orig</EM><STRONG>,</STRONG> + <STRONG>int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>,</STRONG> + <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>mvderwin(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>par</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>par</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG> + <STRONG>WINDOW</STRONG> <STRONG>*</STRONG> <STRONG>dupwin(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>wsyncup(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>syncok(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>wcursyncup(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>);</STRONG> + <STRONG>void</STRONG> <STRONG>wsyncdown(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> @@ -90,16 +88,16 @@ Regardless of the function used for creating a new window (e.g., <STRONG>newwin</STRONG>, <STRONG>subwin</STRONG>, <STRONG>derwin</STRONG>, <STRONG>newpad</STRONG>), rather than a duplicate (with <STRONG>dupwin</STRONG>), - all of the window modes are initialized to the default values. These - functions set window modes after a window is created: + all of the window modes are initialized to the default values. The + following functions set a window's modes after it is created: - <STRONG>idcok</STRONG> <STRONG>idlok</STRONG> <STRONG>immedok</STRONG> <STRONG>keypad</STRONG> <STRONG>leaveok</STRONG> <STRONG>nodelay</STRONG> <STRONG>scrollok</STRONG> <STRONG>setscrreg</STRONG> - <STRONG>syncok</STRONG> <STRONG>wbkgdset</STRONG> <STRONG>wbkgrndset</STRONG> and <STRONG>wtimeout</STRONG>. + <STRONG>idcok</STRONG>, <STRONG>idlok</STRONG>, <STRONG>immedok</STRONG>, <STRONG>keypad</STRONG>, <STRONG>leaveok</STRONG>, <STRONG>nodelay</STRONG>, <STRONG>notimeout</STRONG>, + <STRONG>scrollok</STRONG>, <STRONG>setscrreg</STRONG>, <STRONG>syncok</STRONG>, <STRONG>wbkgdset</STRONG>, <STRONG>wbkgrndset</STRONG>, and <STRONG>wtimeout</STRONG>. </PRE><H3><a name="h3-delwin">delwin</a></H3><PRE> - Calling <STRONG>delwin</STRONG> deletes the named window, freeing all memory associated - with it (it does not actually erase the window's screen image). + Calling <STRONG>delwin</STRONG> deletes the named window, freeing all memory associated + with it (it does not actually erase the window's screen image). Subwindows must be deleted before the main window can be deleted. @@ -114,22 +112,22 @@ Calling <STRONG>subwin</STRONG> creates and returns a pointer to a new window with the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>. The window is at position (<EM>begin</EM>_<EM>y</EM>, <EM>begin</EM>_<EM>x</EM>) on the screen. The subwindow shares memory - with the window <EM>orig</EM>, its <EM>ancestor</EM>, so that changes made to one window - will affect both windows. When using this routine, it is necessary to - call <STRONG>touchwin</STRONG> or <STRONG>touchline</STRONG> on <EM>orig</EM> before calling <STRONG>wrefresh</STRONG> on the + with the window <EM>orig</EM>, its <EM>ancestor</EM>, so that changes made to one window + will affect both windows. When using this routine, it is necessary to + call <STRONG>touchwin</STRONG> or <STRONG>touchline</STRONG> on <EM>orig</EM> before calling <STRONG>wrefresh</STRONG> on the subwindow. </PRE><H3><a name="h3-derwin">derwin</a></H3><PRE> - Calling <STRONG>derwin</STRONG> is the same as calling <STRONG>subwin,</STRONG> except that <EM>begin</EM>_<EM>y</EM> and - <EM>begin</EM>_<EM>x</EM> are relative to the origin of the window <EM>orig</EM> rather than the - screen. There is no difference between the subwindows and the derived + Calling <STRONG>derwin</STRONG> is the same as calling <STRONG>subwin,</STRONG> except that <EM>begin</EM>_<EM>y</EM> and + <EM>begin</EM>_<EM>x</EM> are relative to the origin of the window <EM>orig</EM> rather than the + screen. There is no difference between the subwindows and the derived windows. </PRE><H3><a name="h3-mvderwin">mvderwin</a></H3><PRE> - Calling <STRONG>mvderwin</STRONG> moves a derived window (or subwindow) inside its - parent window. The screen-relative parameters of the window are not + Calling <STRONG>mvderwin</STRONG> moves a derived window (or subwindow) inside its + parent window. The screen-relative parameters of the window are not changed. This routine is used to display different parts of the parent window at the same physical position on the screen. @@ -158,95 +156,81 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Routines that return an integer return the integer <STRONG>ERR</STRONG> upon failure and - <STRONG>OK</STRONG> (SVr4 only specifies "an integer value other than <STRONG>ERR</STRONG>") upon - successful completion. + Functions that return integers return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> upon + success. + + Functions that return pointers return a null pointer on failure. - Routines that return pointers return <STRONG>NULL</STRONG> on error. + <EM>ncurses</EM> defines several error conditions. - X/Open defines no error conditions. In this implementation + <STRONG>o</STRONG> <STRONG>delwin</STRONG> returns <STRONG>ERR</STRONG> if <EM>win</EM> is a null pointer, or if it is the parent + of another window. - <STRONG>delwin</STRONG> - returns an error if the window pointer is null, or if the window - is the parent of another window. + <EM>ncurses</EM> maintains a list of windows, and checks that the pointer + passed to <STRONG>delwin</STRONG> is one that it created, returning <STRONG>ERR</STRONG> if it was + not. - <STRONG>derwin</STRONG> - returns an error if the parent window pointer is null, or if any - of its ordinates or dimensions is negative, or if the resulting - window does not fit inside the parent window. + <STRONG>o</STRONG> <STRONG>derwin</STRONG> returns <STRONG>ERR</STRONG> if <EM>orig</EM> is a null pointer, or if any of the + ordinate or dimension arguments is negative, or if the resulting + window does not fit inside the parent window. - <STRONG>dupwin</STRONG> - returns an error if the window pointer is null. + <STRONG>o</STRONG> <STRONG>dupwin</STRONG> returns <STRONG>ERR</STRONG> if <EM>win</EM> is a null pointer. - This implementation also maintains a list of windows, and checks - that the pointer passed to <STRONG>delwin</STRONG> is one that it created, - returning an error if it was not.. + <STRONG>o</STRONG> <STRONG>mvderwin</STRONG> returns <STRONG>ERR</STRONG> if <EM>win</EM> is a null pointer, or if any part of + the window would be placed off-screen. - <STRONG>mvderwin</STRONG> - returns an error if the window pointer is null, or if some part of - the window would be placed off-screen. + <STRONG>o</STRONG> <STRONG>mvwin</STRONG> returns <STRONG>ERR</STRONG> if <EM>win</EM> is a null pointer, if <EM>win</EM> is a pad, or if + any part of the window would be placed off-screen. - <STRONG>mvwin</STRONG> - returns an error if the window pointer is null, or if the window - is really a pad, or if some part of the window would be placed - off-screen. + <STRONG>o</STRONG> <STRONG>newwin</STRONG> returns <STRONG>ERR</STRONG> if any of its arguments is negative. - <STRONG>newwin</STRONG> - will fail if either of its beginning ordinates is negative, or if - either the number of lines or columns is negative. + <STRONG>o</STRONG> <STRONG>subwin</STRONG> returns <STRONG>ERR</STRONG> if <EM>orig</EM> is a null pointer, or if any of the + ordinate or dimension arguments is negative, or if the resulting + window does not fit inside the parent window. - <STRONG>syncok</STRONG> - returns an error if the window pointer is null. + <STRONG>o</STRONG> <STRONG>syncok</STRONG> returns <STRONG>ERR</STRONG> if <EM>win</EM> is a null pointer. - <STRONG>subwin</STRONG> - returns an error if the parent window pointer is null, or if any - of its ordinates or dimensions is negative, or if the resulting - window does not fit inside the parent window. + Functions that return a window pointer fail if memory allocation for + their data structures fails. - The functions which return a window pointer may also fail if there is - insufficient memory for its data structures. Any of these functions - will fail if the screen has not been initialized, i.e., with <STRONG>initscr</STRONG> or - <STRONG>newterm</STRONG>. + All of these functions fail if the screen has not been initialized; see + <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - If many small changes are made to the window, the <STRONG>wsyncup</STRONG> option could - degrade performance. + <STRONG>syncok</STRONG> may be implemented as a macro. - Note that <STRONG>syncok</STRONG> may be a macro. + Calling <STRONG>syncup</STRONG> on a window and making many small changes to it could + degrade performance. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 4 describes these functions. + X/Open Curses Issue 4 describes these functions. It specifies no error + conditions for <EM>delwin</EM>, <EM>derwin</EM>, <EM>dupwin</EM>, <EM>newwin</EM>, <EM>mvderwin</EM>, or <EM>syncok</EM>. - X/Open Curses states regarding <STRONG>delwin</STRONG>: + For functions returning integers (except <EM>delwin</EM>), SVr4 describes a + successful return value only as "an integer value other than <EM>ERR</EM>". - <STRONG>o</STRONG> It must delete subwindows before deleting their parent. + Regarding <EM>delwin</EM>, X/Open Curses states that - <STRONG>o</STRONG> If <STRONG>delwin</STRONG> is asked to delete a parent window, it can only succeed - if the curses library keeps a list of the subwindows. SVr4 curses - kept a count of the number of subwindows rather than a list. It - simply returned <STRONG>ERR</STRONG> when asked to delete a subwindow. Solaris - X/Open curses does not even make that check, and will delete a - parent window which still has subwindows. + [t]he application must delete subwindows before deleting the + main window. - <STRONG>o</STRONG> Since release 4.0 (1996), <EM>ncurses</EM> maintains a list of windows for - each screen, to ensure that a window has no subwindows before - allowing deletion. + If <EM>delwin</EM> is asked to delete a parent window, it can succeed only if + the <EM>curses</EM> library keeps a list of its subwindows. SVr4 <EM>curses</EM> kept a + count of the number of subwindows rather than a list. It simply + returned <STRONG>ERR</STRONG> when asked to delete a subwindow. Solaris X/Open <EM>curses</EM> + (<EM>xcurses</EM>) does not make even that check, and will delete a parent + window that still has subwindows. <EM>PDCurses</EM> also behaves this way. - <STRONG>o</STRONG> NetBSD copied this feature of <EM>ncurses</EM> in 2003. - PDCurses follows the scheme used in Solaris X/Open curses. + <EM>ncurses</EM> 4.0 (1996) and later maintains a list of windows for each + screen to ensure that a window has no subwindows before allowing its + deletion. NetBSD <EM>curses</EM> has followed suit since 2003. - -</PRE><H2><a name="h2-BUGS">BUGS</a></H2><PRE> - The subwindow functions <STRONG>subwin</STRONG>, <STRONG>derwin</STRONG>, <STRONG>mvderwin</STRONG>, <STRONG>wsyncup</STRONG>, <STRONG>wsyncdown</STRONG>, - <STRONG>wcursyncup</STRONG>, and <STRONG>syncok</STRONG> are flaky, incompletely implemented, and not - well tested. - - System V's <EM>curses</EM> documentation is unclear about what <STRONG>wsyncup</STRONG> and - <STRONG>wsyncdown</STRONG> actually do. It seems to imply that they are supposed to - touch only those lines that are affected by changes to a window's - ancestors. The language here, and behavior of <EM>ncurses</EM>, is patterned on + SVr4 <EM>curses</EM> documentation is unclear about what <EM>wsyncup</EM> and <EM>wsyncdown</EM> + actually do. It seems to imply that they are supposed to touch only + those lines that are affected by changes to a window's ancestors. The + description and behavior of these functions in <EM>ncurses</EM> is patterned on the X/Open Curses standard; this approach may result in slower updates. @@ -254,9 +238,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG> +ncurses 6.6 2025-08-23 <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -279,7 +261,6 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF=" <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> -<li><a href="#h2-BUGS">BUGS</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> </div> diff --git a/doc/html/man/default_colors.3x.html b/doc/html/man/default_colors.3x.html index 14a0f8e36507..9cae26e64f58 100644 --- a/doc/html/man/default_colors.3x.html +++ b/doc/html/man/default_colors.3x.html @@ -35,18 +35,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>default_colors 3x 2024-04-13 ncurses 6.5 Library calls</TITLE> +<TITLE>default_colors 3x 2024-04-13 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">default_colors 3x 2024-04-13 ncurses 6.5 Library calls</H1> +<H1 class="no-header">default_colors 3x 2024-04-13 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG> Library calls <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>use_default_colors</STRONG>, <STRONG>assume_default_colors</STRONG> - use terminal's default colors in <EM>curses</EM> @@ -70,9 +68,9 @@ not take advantage of SGR 39 and SGR 49. Some applications are designed to work with the default background, using colors only for text. For example, there are several implementations of the <STRONG>ls</STRONG> program - which use colors to denote different file types or permissions. These - "color ls" programs do not necessarily modify the background color, - typically using only the <STRONG>setaf</STRONG> terminfo capability to set the + which use colors to denote different file types or permissions. These + "color ls" programs do not necessarily modify the background color, + typically using only the <STRONG>setaf</STRONG> terminfo capability to set the foreground color. Full-screen applications that use default colors can achieve similar visual effects. @@ -103,7 +101,7 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - These functions return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success. + These functions return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success. They will fail if either the terminal does not support the <STRONG>orig_pair</STRONG> or <STRONG>orig_colors</STRONG> capability. If the <STRONG>initialize_pair</STRONG> capability is not found, this causes an error as well. @@ -113,8 +111,8 @@ Associated with this extension, the <STRONG>init_pair</STRONG> function accepts negative arguments to specify default foreground or background colors. - The <STRONG>use_default_colors</STRONG> function was added to support <STRONG>ded</STRONG>. This is a - full-screen application which uses curses to manage only part of the + The <STRONG>use_default_colors</STRONG> function was added to support <STRONG>ded</STRONG>. This is a + full-screen application which uses curses to manage only part of the screen. The bottom portion of the screen, which is of adjustable size, is left uncolored to display the results from shell commands. The top portion of the screen colors filenames using a scheme like the "color @@ -129,12 +127,12 @@ The <STRONG>assume_default_colors</STRONG> function was added to solve a different problem: support for applications which would use environment variables - and other configuration to bypass curses' notion of the terminal's + and other configuration to bypass curses' notion of the terminal's default colors, setting specific values. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines are specific to <EM>ncurses</EM>. They were not supported on + These routines are specific to <EM>ncurses</EM>. They were not supported on Version 7, BSD or System V implementations. It is recommended that any code depending on them be conditioned using NCURSES_VERSION. @@ -147,9 +145,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG>ded(1)</STRONG>, <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> - - -ncurses 6.5 2024-04-13 <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG> +ncurses 6.6 2024-04-13 <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/define_key.3x.html b/doc/html/man/define_key.3x.html index d135e3109948..7152733bef10 100644 --- a/doc/html/man/define_key.3x.html +++ b/doc/html/man/define_key.3x.html @@ -28,57 +28,65 @@ * authorization. * **************************************************************************** * Author: Thomas E. Dickey 1997 - * @Id: define_key.3x,v 1.42 2024/03/16 15:35:01 tom Exp @ + * @Id: define_key.3x,v 1.52 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>define_key 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>define_key 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">define_key 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">define_key 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> Library calls <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>define_key</STRONG> - define a <EM>curses</EM> keycode + <STRONG>define_key</STRONG> - define a <EM>curses</EM> function key code </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>define_key(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>definition</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>keycode</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>define_key(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>definition</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>key-code</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - This is an extension to the <EM>curses</EM> library. It permits an application - to define keycodes with their corresponding control strings, so that - the <EM>ncurses</EM> library will interpret them just as it would the predefined - codes in the terminfo database. + The <STRONG>define_key</STRONG> <EM>ncurses</EM> extension permits a <EM>curses</EM> application to <EM>bind</EM> a + string <EM>definition</EM> to the function key <EM>key-code</EM> returned by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> + (wide-character API users: <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG>) when <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> is enabled in + a window and a function key is pressed. <EM>ncurses</EM> interprets such a + binding as it does those in the <EM>terminfo</EM> database entry for the + terminal type. - If <EM>definition</EM> is <STRONG>NULL</STRONG>, any existing one for the keycode is removed. - Similarly, if the given keycode is negative or zero, any existing - string for the given definition is removed. + A <EM>definition</EM> of <EM>NULL</EM> removes any existing binding from <EM>key-code</EM>. + Similarly, a non-positive <EM>key-code</EM> removes an existing binding for + <EM>definition</EM>, if any. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Either <EM>keycode</EM> must be greater than zero, or <EM>definition</EM> must be non- - <STRONG>NULL</STRONG>, otherwise <STRONG>ERR</STRONG> is returned. <STRONG>ERR</STRONG> may also be returned if there is - insufficient memory to allocate the data to store the definition. If - no error is detected, <STRONG>OK</STRONG> is returned. + <STRONG>define_key</STRONG> returns <STRONG>ERR</STRONG> if + + <STRONG>o</STRONG> <EM>definition</EM> is <EM>NULL</EM> and <EM>key-code</EM> is nonpositive, or + + <STRONG>o</STRONG> insufficient memory is available to bind <EM>definition</EM> to <EM>key-code</EM>. + + Otherwise, <STRONG>define_key</STRONG> returns <STRONG>OK</STRONG>. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>define_key</STRONG> is an <EM>ncurses</EM> extension. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines are specific to <EM>ncurses</EM>. They were not supported on - Version 7, BSD or System V implementations. It is recommended that any - code depending on them be conditioned using <STRONG>NCURSES_VERSION</STRONG>. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + + NetBSD <EM>curses</EM> since 2.0 (2004) supports <EM>define</EM><STRONG>_</STRONG><EM>key</EM>. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> @@ -86,11 +94,9 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>, <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> - - + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG>, <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>, <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> -ncurses 6.5 2024-03-16 <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -98,6 +104,7 @@ ncurses 6.5 2024-03-16 <STRONG><A HREF= <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-AUTHORS">AUTHORS</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> diff --git a/doc/html/man/form.3x.html b/doc/html/man/form.3x.html index fcdb7af1f5a7..3f021e0106b6 100644 --- a/doc/html/man/form.3x.html +++ b/doc/html/man/form.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,27 +28,25 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form.3x,v 1.54 2024/03/16 15:35:01 tom Exp @ + * @Id: form.3x,v 1.62 2025/11/12 01:27:41 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> Library calls <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>form</STRONG> - curses extension for programming forms + <STRONG>form</STRONG> - present user-fillable forms in <EM>curses</EM> windows </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> @@ -57,7 +55,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The <STRONG>form</STRONG> library provides terminal-independent facilities for composing - form screens on character-cell terminals. The library includes: field + form screens on character-cell terminals. The library includes: field routines, which create and modify form fields; and form routines, which group fields into forms, display forms on the screen, and handle interaction with the user. @@ -78,7 +76,7 @@ </PRE><H3><a name="h3-Current-Default-Values-for-Field-Attributes">Current Default Values for Field Attributes</a></H3><PRE> The <STRONG>form</STRONG> library maintains a default value for field attributes. You can get or set this default by calling the appropriate <STRONG>set_</STRONG> or - retrieval routine with a <STRONG>NULL</STRONG> field pointer. Changing this default + retrieval routine with a <EM>NULL</EM> field pointer. Changing this default with a <STRONG>set_</STRONG> function affects future field creations, but does not change the rendering of fields already created. @@ -112,7 +110,6 @@ field_term <STRONG><A HREF="form_hook.3x.html">form_hook(3x)</A></STRONG> field_type <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG> field_userptr <STRONG><A HREF="form_field_userptr.3x.html">form_field_userptr(3x)</A></STRONG> - form_driver <STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG> form_driver_w <STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG>* form_fields <STRONG><A HREF="form_field.3x.html">form_field(3x)</A></STRONG> @@ -169,7 +166,7 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Routines that return pointers return <STRONG>NULL</STRONG> on error, and set <STRONG>errno</STRONG> to + Routines that return pointers return <EM>NULL</EM> on error, and set <STRONG>errno</STRONG> to the corresponding error-code returned by functions returning an integer. Routines that return an integer return one of the following error codes: @@ -243,9 +240,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "form_" for detailed descriptions of the entry points. - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_cursor.3x.html b/doc/html/man/form_cursor.3x.html index 5844dd58d9d2..545e4af695a9 100644 --- a/doc/html/man/form_cursor.3x.html +++ b/doc/html/man/form_cursor.3x.html @@ -35,18 +35,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_cursor 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_cursor 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_cursor 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_cursor 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_cursor.3x.html">form_cursor(3x)</A></STRONG> Library calls <STRONG><A HREF="form_cursor.3x.html">form_cursor(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>pos_form_cursor</STRONG> - position a form window cursor @@ -60,7 +58,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>pos_form_cursor</STRONG> restores the cursor to the position required for the forms driver to continue processing requests. This is - useful after <STRONG>curses</STRONG> routines have been called to do screen-painting in + useful after <STRONG>curses</STRONG> routines have been called to do screen-painting in response to a form operation. @@ -80,7 +78,7 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V forms library. They were not + These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions. @@ -92,9 +90,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_cursor.3x.html">form_cursor(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="form_cursor.3x.html">form_cursor(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_data.3x.html b/doc/html/man/form_data.3x.html index 2f1dc3b9016c..0294d482194f 100644 --- a/doc/html/man/form_data.3x.html +++ b/doc/html/man/form_data.3x.html @@ -35,18 +35,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_data 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_data 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_data 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_data 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_data.3x.html">form_data(3x)</A></STRONG> Library calls <STRONG><A HREF="form_data.3x.html">form_data(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>data_ahead</STRONG>, <STRONG>data_behind</STRONG> - test for off-screen data in given forms @@ -62,12 +60,12 @@ The function <STRONG>data_ahead</STRONG> tests whether there is off-screen data ahead in the given form. It returns TRUE (1) or FALSE (0). - The function <STRONG>data_behind</STRONG> tests whether there is off-screen data behind + The function <STRONG>data_behind</STRONG> tests whether there is off-screen data behind in the given form. It returns TRUE (1) or FALSE (0). </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V forms library. They were not + These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions. @@ -79,9 +77,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_data.3x.html">form_data(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="form_data.3x.html">form_data(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_driver.3x.html b/doc/html/man/form_driver.3x.html index 859c291a77bb..7a082f6ace08 100644 --- a/doc/html/man/form_driver.3x.html +++ b/doc/html/man/form_driver.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_driver.3x,v 1.61 2024/04/20 18:55:09 tom Exp @ + * @Id: form_driver.3x,v 1.64 2025/10/04 20:59:08 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_driver 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>form_driver 3x 2025-10-04 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_driver 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_driver 3x 2025-10-04 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG> Library calls <STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>form_driver</STRONG>, <STRONG>form_driver_w</STRONG> - command-processing loop of the form system @@ -64,21 +62,21 @@ Once a form has been posted (displayed), you should funnel input events to it through <STRONG>form_driver</STRONG>. This routine has three major input cases: - <STRONG>o</STRONG> The input is a form navigation request. Navigation request codes - are constants defined in <STRONG><form.h></STRONG>, which are distinct from the key- + <STRONG>o</STRONG> The input is a form navigation request. Navigation request codes + are constants defined in <EM>form.h</EM>, which are distinct from the key- and character codes returned by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>. - <STRONG>o</STRONG> The input is a printable character. Printable characters (which - must be positive, less than 256) are checked according to the + <STRONG>o</STRONG> The input is a printable character. Printable characters (which + must be positive, less than 256) are checked according to the program's locale settings. - <STRONG>o</STRONG> The input is the KEY_MOUSE special key associated with an mouse + <STRONG>o</STRONG> The input is the KEY_MOUSE special key associated with an mouse event. </PRE><H3><a name="h3-form_driver_w">form_driver_w</a></H3><PRE> - This extension simplifies the use of the forms library using wide - characters. The input is either a key code (a request) or a wide + This extension simplifies the use of the forms library using wide + characters. The input is either a key code (a request) or a wide character returned by <STRONG><A HREF="curs_get_wch.3x.html">get_wch(3x)</A></STRONG>. The type must be passed as well, to enable the library to determine whether the parameter is a wide character or a request. @@ -113,7 +111,6 @@ <STRONG>REQ_LEFT_FIELD</STRONG> Move left to a field. <STRONG>REQ_NEW_LINE</STRONG> Insert or overlay a new line. <STRONG>REQ_NEXT_CHAR</STRONG> Move to the next char. - <STRONG>REQ_NEXT_CHOICE</STRONG> Display next field choice. <STRONG>REQ_NEXT_FIELD</STRONG> Move to the next field. <STRONG>REQ_NEXT_LINE</STRONG> Move to the next line. @@ -207,22 +204,22 @@ <STRONG>o</STRONG> the form cursor is positioned to that field. - <STRONG>o</STRONG> If you double-click a field, the form cursor is positioned to + <STRONG>o</STRONG> If you double-click a field, the form cursor is positioned to that field and <STRONG>E_UNKNOWN_COMMAND</STRONG> is returned. This return value makes sense, because a double click usually means that an field- - specific action should be returned. It is exactly the purpose - of this return value to signal that an application specific + specific action should be returned. It is exactly the purpose + of this return value to signal that an application specific command should be executed. - <STRONG>o</STRONG> If a translation into a request was done, <STRONG>form_driver</STRONG> returns + <STRONG>o</STRONG> If a translation into a request was done, <STRONG>form_driver</STRONG> returns the result of this request. - If you clicked outside the user window or the mouse event could not be + If you clicked outside the user window or the mouse event could not be translated into a form request an <STRONG>E_REQUEST_DENIED</STRONG> is returned. </PRE><H3><a name="h3-Application-defined-Commands">Application-defined Commands</a></H3><PRE> - If the second argument is neither printable nor one of the above pre- + If the second argument is neither printable nor one of the above pre- defined form requests, the driver assumes it is an application-specific command and returns <STRONG>E_UNKNOWN_COMMAND</STRONG>. Application-defined commands should be defined relative to <STRONG>MAX_COMMAND</STRONG>, the maximum value of these @@ -270,12 +267,10 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG>, <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG>, + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG>, <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG>, <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG>, <STRONG><A HREF="form_variables.3x.html">form_variables(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG> +ncurses 6.6 2025-10-04 <STRONG><A HREF="form_driver.3x.html">form_driver(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_field.3x.html b/doc/html/man/form_field.3x.html index 8eb58d4c62a2..614fc7ef12ad 100644 --- a/doc/html/man/form_field.3x.html +++ b/doc/html/man/form_field.3x.html @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_field.3x,v 1.34 2024/03/16 15:35:01 tom Exp @ + * @Id: form_field.3x,v 1.36 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_field 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_field 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_field 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_field 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_field.3x.html">form_field(3x)</A></STRONG> Library calls <STRONG><A HREF="form_field.3x.html">form_field(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>form_field</STRONG> - make and break connections between fields and forms @@ -62,7 +60,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>set_form_fields</STRONG> changes the field pointer array of the - given <EM>form</EM>. The array must be terminated by a <STRONG>NULL</STRONG>. + given <EM>form</EM>. The array must be terminated by a <EM>NULL</EM>. The function <STRONG>form_fields</STRONG> returns the field array of the given form. @@ -73,10 +71,10 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The function <STRONG>form_fields</STRONG> returns a pointer (which may be <STRONG>NULL</STRONG>). It + The function <STRONG>form_fields</STRONG> returns a pointer (which may be <EM>NULL</EM>). It does not set <STRONG>errno</STRONG>. - The function <STRONG>field_count</STRONG> returns <STRONG>ERR</STRONG> if the <EM>form</EM> parameter is <STRONG>NULL</STRONG>. + The function <STRONG>field_count</STRONG> returns <STRONG>ERR</STRONG> if the <EM>form</EM> parameter is <EM>NULL</EM>. The functions <STRONG>set_form_fields</STRONG> and <STRONG>move_field</STRONG> return one of the following codes on error: @@ -112,9 +110,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_field.3x.html">form_field(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="form_field.3x.html">form_field(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_field_attributes.3x.html b/doc/html/man/form_field_attributes.3x.html index 22afdc67971d..1280f7fb2214 100644 --- a/doc/html/man/form_field_attributes.3x.html +++ b/doc/html/man/form_field_attributes.3x.html @@ -35,18 +35,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_field_attributes 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_field_attributes 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_field_attributes 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_field_attributes 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3x)</A></STRONG> Library calls <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>form_field_attributes</STRONG> - color and attribute control for form fields @@ -67,7 +65,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>set_field_fore</STRONG> sets the foreground attribute of <EM>field</EM>. This is the highlight used to display the field contents. The function - <STRONG>field_fore</STRONG> returns the foreground attribute. The default is + <STRONG>field_fore</STRONG> returns the foreground attribute. The default is <STRONG>A_STANDOUT</STRONG>. The function <STRONG>set_field_back</STRONG> sets the background attribute of <EM>form</EM>. This @@ -103,12 +101,10 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "form_" for detailed + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "form_" for detailed descriptions of the entry points. - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="form_field_attributes.3x.html">form_field_attributes(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_field_buffer.3x.html b/doc/html/man/form_field_buffer.3x.html index 47d6c8b3e421..0ef52348034a 100644 --- a/doc/html/man/form_field_buffer.3x.html +++ b/doc/html/man/form_field_buffer.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_field_buffer.3x,v 1.45 2024/03/16 15:35:01 tom Exp @ + * @Id: form_field_buffer.3x,v 1.47 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_field_buffer 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_field_buffer 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_field_buffer 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_field_buffer 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG> Library calls <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>form_field_buffer</STRONG> - field buffer control @@ -87,12 +85,12 @@ <STRONG>o</STRONG> Editing operations are based on the <EM>window</EM> which displays the field, rather than a <EM>string</EM>. The window contains only printable - characters, and is filled with blanks. If you want the raw - data, you must write your own routine that copies the value out + characters, and is filled with blanks. If you want the raw + data, you must write your own routine that copies the value out of the buffer and removes the leading and trailing spaces. - <STRONG>o</STRONG> Because editing operations change the content of the buffer to - correspond to the window, you should not rely on using buffers + <STRONG>o</STRONG> Because editing operations change the content of the buffer to + correspond to the window, you should not rely on using buffers for long-term storage of form data. The function <STRONG>set_field_status</STRONG> sets the associated status flag of <EM>field</EM>; @@ -104,7 +102,7 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The <STRONG>field_buffer</STRONG> function returns NULL on error. It sets <STRONG>errno</STRONG> + The <STRONG>field_buffer</STRONG> function returns <EM>NULL</EM> on error. It sets <STRONG>errno</STRONG> according to their success: <STRONG>E_OK</STRONG> The routine succeeded. @@ -133,11 +131,11 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V forms library. They were not + These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions. - The <STRONG>set_max_field</STRONG> function checks for an <EM>ncurses</EM> extension - <STRONG>O_INPUT_FIELD</STRONG> which allows a dynamic field to shrink if the new limit + The <STRONG>set_max_field</STRONG> function checks for an <EM>ncurses</EM> extension + <STRONG>O_INPUT_FIELD</STRONG> which allows a dynamic field to shrink if the new limit is smaller than the current field size. @@ -150,9 +148,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "form_" for detailed descriptions of the entry points. - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="form_field_buffer.3x.html">form_field_buffer(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_field_info.3x.html b/doc/html/man/form_field_info.3x.html index 2090ab669ced..f86c1b004c62 100644 --- a/doc/html/man/form_field_info.3x.html +++ b/doc/html/man/form_field_info.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_field_info 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_field_info 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_field_info 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_field_info 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_field_info.3x.html">form_field_info(3x)</A></STRONG> Library calls <STRONG><A HREF="form_field_info.3x.html">form_field_info(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>dynamic_field_info</STRONG>, <STRONG>field_info</STRONG> - retrieve field characteristics @@ -87,11 +85,11 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V forms library. They were not + These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions. - A null (zero pointer) is accepted for any of the return values, to - ignore that value. Not all implementations allow this, e.g., Solaris + A null (zero pointer) is accepted for any of the return values, to + ignore that value. Not all implementations allow this, e.g., Solaris 2.7 does not. @@ -104,9 +102,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "form_" for detailed descriptions of the entry points. - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_field_info.3x.html">form_field_info(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="form_field_info.3x.html">form_field_info(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_field_just.3x.html b/doc/html/man/form_field_just.3x.html index f0bc457faf24..c8a247bf2392 100644 --- a/doc/html/man/form_field_just.3x.html +++ b/doc/html/man/form_field_just.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_field_just 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_field_just 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_field_just 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_field_just 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_field_just.3x.html">form_field_just(3x)</A></STRONG> Library calls <STRONG><A HREF="form_field_just.3x.html">form_field_just(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_field_just</STRONG>, <STRONG>field_just</STRONG> - retrieve field characteristics @@ -90,12 +88,10 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "form_" for detailed + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "form_" for detailed descriptions of the entry points. - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_field_just.3x.html">form_field_just(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="form_field_just.3x.html">form_field_just(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_field_new.3x.html b/doc/html/man/form_field_new.3x.html index c7bedd9a214c..3cfc745576c5 100644 --- a/doc/html/man/form_field_new.3x.html +++ b/doc/html/man/form_field_new.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_field_new.3x,v 1.41 2024/03/16 15:35:01 tom Exp @ + * @Id: form_field_new.3x,v 1.43 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_field_new 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_field_new 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_field_new 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_field_new 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_field_new.3x.html">form_field_new(3x)</A></STRONG> Library calls <STRONG><A HREF="form_field_new.3x.html">form_field_new(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>new_field</STRONG>, <STRONG>dup_field</STRONG>, <STRONG>link_field</STRONG>, <STRONG>free_field</STRONG> - create and destroy form fields @@ -74,14 +72,14 @@ character, options, and user pointer) are copied. Field status and the field page bit are not copied. - The function <STRONG>link_field</STRONG> acts like <STRONG>dup_field</STRONG>, but the new field shares + The function <STRONG>link_field</STRONG> acts like <STRONG>dup_field</STRONG>, but the new field shares buffers with its parent. Attribute data is separate. The function <STRONG>free_field</STRONG> de-allocates storage associated with a field. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The functions <STRONG>new_field</STRONG>, <STRONG>dup_field</STRONG>, <STRONG>link_field</STRONG> return <STRONG>NULL</STRONG> on error. + The functions <STRONG>new_field</STRONG>, <STRONG>dup_field</STRONG>, <STRONG>link_field</STRONG> return <EM>NULL</EM> on error. They set <STRONG>errno</STRONG> according to their success: <STRONG>E_OK</STRONG> The routine succeeded. @@ -104,11 +102,11 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V forms library. They were not + These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions. - It may be unwise to count on the set of attributes copied by <STRONG>dup_field</STRONG> - being portable; the System V forms library documents are not very + It may be unwise to count on the set of attributes copied by <STRONG>dup_field</STRONG> + being portable; the System V forms library documents are not very explicit about what gets copied and what does not. @@ -120,9 +118,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_field_new.3x.html">form_field_new(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="form_field_new.3x.html">form_field_new(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_field_opts.3x.html b/doc/html/man/form_field_opts.3x.html index 52fca0a5a333..114d21e566bc 100644 --- a/doc/html/man/form_field_opts.3x.html +++ b/doc/html/man/form_field_opts.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2014,2015 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_field_opts.3x,v 1.44 2024/03/16 15:35:01 tom Exp @ + * @Id: form_field_opts.3x,v 1.47 2025/01/19 00:51:10 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_field_opts 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_field_opts 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_field_opts 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_field_opts 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3x)</A></STRONG> Library calls <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_field_opts</STRONG>, <STRONG>field_opts_on</STRONG>, <STRONG>field_opts_off</STRONG>, <STRONG>field_opts</STRONG> - set and get field options @@ -62,10 +60,10 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The function <STRONG>set_field_opts</STRONG> sets all the given field's option bits - (field option bits may be logically-OR'ed together). + The function <STRONG>set_field_opts</STRONG> sets all the given field's option bits + (field option bits may be logically "or"-ed together). - The function <STRONG>field_opts_on</STRONG> turns on the given option bits, and leaves + The function <STRONG>field_opts_on</STRONG> turns on the given option bits, and leaves others alone. The function <STRONG>field_opts_off</STRONG> turns off the given option bits, and leaves @@ -84,7 +82,7 @@ Skip to the next field when this one fills. O_BLANK - The field is cleared whenever a character is entered at the first + The field is cleared whenever a character is entered at the first position. O_EDIT @@ -100,15 +98,15 @@ The field contents are displayed as data is entered. O_STATIC - Field buffers are fixed to field's original size. Turn this + Field buffers are fixed to field's original size. Turn this option off to create a dynamic field. O_VISIBLE - The field is displayed. If this option is off, display of the + The field is displayed. If this option is off, display of the field is suppressed. O_WRAP - Words that do not fit on a line are wrapped to the next line. + Words that do not fit on a line are wrapped to the next line. Words are blank-separated. These extension options are defined (extensions are off by default): @@ -130,7 +128,7 @@ O_INPUT_FIELD The <STRONG>set_max_field</STRONG> function checks for this extension, which allows - a dynamic field to shrink if the new limit is smaller than the + a dynamic field to shrink if the new limit is smaller than the current field size. @@ -150,7 +148,7 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V forms library. They were not + These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions. @@ -162,9 +160,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, <STRONG><A HREF="form_field_just.3x.html">form_field_just(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="form_field_opts.3x.html">form_field_opts(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_field_userptr.3x.html b/doc/html/man/form_field_userptr.3x.html index 128698edb249..d42956cc3336 100644 --- a/doc/html/man/form_field_userptr.3x.html +++ b/doc/html/man/form_field_userptr.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_field_userptr.3x,v 1.30 2024/03/16 15:35:01 tom Exp @ + * @Id: form_field_userptr.3x,v 1.32 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_field_userptr 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_field_userptr 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_field_userptr 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_field_userptr 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_field_userptr.3x.html">form_field_userptr(3x)</A></STRONG> Library calls <STRONG><A HREF="form_field_userptr.3x.html">form_field_userptr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_field_userptr</STRONG>, <STRONG>field_userptr</STRONG> - associate application data with a form field @@ -65,7 +63,7 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The function <STRONG>field_userptr</STRONG> returns a pointer (which may be <STRONG>NULL</STRONG>). It + The function <STRONG>field_userptr</STRONG> returns a pointer (which may be <EM>NULL</EM>). It does not set <STRONG>errno</STRONG>. The function <STRONG>set_field_userptr</STRONG> returns <STRONG>E_OK</STRONG> (success). @@ -87,9 +85,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_field_userptr.3x.html">form_field_userptr(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="form_field_userptr.3x.html">form_field_userptr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_field_validation.3x.html b/doc/html/man/form_field_validation.3x.html index e66d71c26462..93e496e513d2 100644 --- a/doc/html/man/form_field_validation.3x.html +++ b/doc/html/man/form_field_validation.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_field_validation.3x,v 1.53 2024/03/16 15:35:01 tom Exp @ + * @Id: form_field_validation.3x,v 1.62 2025/08/16 19:11:47 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_field_validation 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_field_validation 3x 2025-08-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_field_validation 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_field_validation 3x 2025-08-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG> Library calls <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>form_field_validation</STRONG> - data type validation for fields @@ -57,7 +55,7 @@ <STRONG>FIELDTYPE</STRONG> <STRONG>*field_type(const</STRONG> <STRONG>FIELD</STRONG> <STRONG>*</STRONG><EM>field</EM><STRONG>);</STRONG> <STRONG>int</STRONG> <STRONG>set_field_type(FIELD</STRONG> <STRONG>*</STRONG><EM>field</EM><STRONG>,</STRONG> <STRONG>FIELDTYPE</STRONG> <STRONG>*</STRONG><EM>type</EM><STRONG>,</STRONG> <STRONG>...);</STRONG> - <EM>/*</EM> <EM>predefined</EM> <EM>field</EM> <EM>types</EM> <EM>*/</EM> + <EM>/*</EM> <EM>field</EM> <EM>types</EM> <EM>*/</EM> <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ALNUM;</STRONG> <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ALPHA;</STRONG> <STRONG>FIELDTYPE</STRONG> <STRONG>*TYPE_ENUM;</STRONG> @@ -69,33 +67,31 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> By default, no validation is done on form fields. You can associate a - form with with a <EM>field</EM> <EM>type</EM>, making the form library validate input. + form with a <EM>field</EM> <EM>type</EM>, making the form library validate input. </PRE><H3><a name="h3-field_arg">field_arg</a></H3><PRE> Returns a pointer to the field's argument block. The <EM>argument</EM> <EM>block</EM> is - an opaque structure containing a copy of the arguments provided in a + an opaque structure containing a copy of the arguments provided in a <STRONG>set_field_type</STRONG> call. </PRE><H3><a name="h3-field_type">field_type</a></H3><PRE> - Returns a pointer to the <EM>field</EM> <EM>type</EM> associated with the form field, + Returns a pointer to the <EM>field</EM> <EM>type</EM> associated with the form field, i.e., by calling <STRONG>set_field_type</STRONG>. </PRE><H3><a name="h3-set_field_type">set_field_type</a></H3><PRE> - The function <STRONG>set_field_type</STRONG> associates a field type with a given form - field. This is the type checked by validation functions. Most field - types are configurable, via arguments which the caller provides when + The function <STRONG>set_field_type</STRONG> associates a field type with a given form + field. This is the type checked by validation functions. Most field + types are configurable, via arguments which the caller provides when calling <STRONG>set_field_type</STRONG>. - Several field types are predefined by the form library. - -</PRE><H2><a name="h2-PREDEFINED-TYPES">PREDEFINED TYPES</a></H2><PRE> - It is possible to set up new programmer-defined field types. Field - types are implemented via the <STRONG>FIELDTYPE</STRONG> data structure, which contains - several pointers to functions. +</PRE><H2><a name="h2-FIELD-TYPES">FIELD TYPES</a></H2><PRE> + The <EM>form</EM> library defines several field types. They are implemented via + the <STRONG>FIELDTYPE</STRONG> data structure, which contains several pointers to + functions. See the <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG> manual page, which describes functions which can be used to construct a field-type dynamically. @@ -122,8 +118,8 @@ <STRONG>o</STRONG> a fourth <STRONG>int</STRONG> flag argument to enable case-sensitivity; - <STRONG>o</STRONG> a fifth <STRONG>int</STRONG> flag argument specifying whether a partial match must - be a unique one. If this flag is off, a prefix matches the first + <STRONG>o</STRONG> a fifth <STRONG>int</STRONG> flag argument specifying whether a partial match must + be a unique one. If this flag is off, a prefix matches the first of any set of more than one list elements with that prefix. The library copies the string list, so you may use a list that lives in @@ -142,7 +138,7 @@ ignored. On return, the field buffer is formatted according to the <STRONG>printf</STRONG> format - specification ".*ld", where the "*" is replaced by the precision + specification ".*ld", where the "*" is replaced by the precision argument. For details of the precision handling see <STRONG>printf(3)</STRONG>. @@ -155,9 +151,9 @@ <STRONG>o</STRONG> a fourth <STRONG>double</STRONG> argument constraining minimum value, - <STRONG>o</STRONG> and a fifth <STRONG>double</STRONG> constraining maximum value. If your system - supports locales, the decimal point character must be the one - specified by your locale. If the maximum value is less than or + <STRONG>o</STRONG> and a fifth <STRONG>double</STRONG> constraining maximum value. If your system + supports locales, the decimal point character must be the one + specified by your locale. If the maximum value is less than or equal to the minimum value, the range is simply ignored. On return, the field buffer is formatted according to the <STRONG>printf</STRONG> format @@ -195,9 +191,11 @@ This is an <EM>ncurses</EM> extension; this field type may not be available in other curses implementations. + It is possible to set up new programmer-defined field types. + </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The functions <STRONG>field_type</STRONG> and <STRONG>field_arg</STRONG> return <STRONG>NULL</STRONG> on error. The + The functions <STRONG>field_type</STRONG> and <STRONG>field_arg</STRONG> return <EM>NULL</EM> on error. The function <STRONG>set_field_type</STRONG> returns one of the following: <STRONG>E_OK</STRONG> The routine succeeded. @@ -219,9 +217,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG>, <STRONG><A HREF="form_variables.3x.html">form_variables(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG> +ncurses 6.6 2025-08-16 <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -234,7 +230,7 @@ ncurses 6.5 2024-03-16 <STRONG><A HREF="form_field <li><a href="#h3-set_field_type">set_field_type</a></li> </ul> </li> -<li><a href="#h2-PREDEFINED-TYPES">PREDEFINED TYPES</a> +<li><a href="#h2-FIELD-TYPES">FIELD TYPES</a> <ul> <li><a href="#h3-TYPE_ALNUM">TYPE_ALNUM</a></li> <li><a href="#h3-TYPE_ALPHA">TYPE_ALPHA</a></li> diff --git a/doc/html/man/form_fieldtype.3x.html b/doc/html/man/form_fieldtype.3x.html index 369f25c5fc11..55035a0fc481 100644 --- a/doc/html/man/form_fieldtype.3x.html +++ b/doc/html/man/form_fieldtype.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2006,2010 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_fieldtype.3x,v 1.46 2024/03/16 15:35:01 tom Exp @ + * @Id: form_fieldtype.3x,v 1.51 2025/01/19 00:51:10 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_fieldtype 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_fieldtype 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_fieldtype 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_fieldtype 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG> Library calls <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>form_fieldtype</STRONG> - define validation-field types @@ -92,12 +90,12 @@ <EM>char</EM><STRONG>_</STRONG><EM>check</EM> This function validates input characters as they are entered. The - form library passes it the character to be checked and a pointer + form library passes it the character to be checked and a pointer to an argument-block structure. </PRE><H3><a name="h3-free_fieldtype">free_fieldtype</a></H3><PRE> - The <STRONG>free_fieldtype</STRONG> function frees the space allocated for a given + The <STRONG>free_fieldtype</STRONG> function frees the space allocated for a given validation type by <STRONG>new_fieldtype</STRONG>. @@ -106,9 +104,9 @@ functions with a field type: <EM>make</EM><STRONG>_</STRONG><EM>arg</EM> - This function is automatically applied to the list of arguments - you give <STRONG>set_field_type</STRONG> when attaching validation to a field. It - stores the arguments in an allocated argument-block object which + This function is automatically applied to the list of arguments + you give <STRONG>set_field_type</STRONG> when attaching validation to a field. It + stores the arguments in an allocated argument-block object which is used when validating input. <EM>copy</EM><STRONG>_</STRONG><EM>arg</EM> @@ -118,7 +116,7 @@ Frees an argument-block structure. You must supply the <EM>make</EM><STRONG>_</STRONG><EM>arg</EM> function. The other two are optional: you - may supply NULL for them. In this case, the form library assumes that + may supply <EM>NULL</EM> for them. In this case, the form library assumes that <EM>make</EM><STRONG>_</STRONG><EM>arg</EM> does not allocate memory but simply loads the argument into a single scalar value. @@ -136,11 +134,11 @@ </PRE><H3><a name="h3-link_fieldtype">link_fieldtype</a></H3><PRE> The function <STRONG>link_fieldtype</STRONG> creates a new field type from the two given - types. They are connected by an logical 'OR'. + types. They are connected by a logical "or". </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The pointer-valued routines return NULL on error. They set <STRONG>errno</STRONG> + The pointer-valued routines return NULL on error. They set <STRONG>errno</STRONG> according to their success: <STRONG>E_OK</STRONG> The routine succeeded. @@ -169,7 +167,7 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V forms library. They were not + These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions. @@ -181,9 +179,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, <STRONG><A HREF="form_field_validation.3x.html">form_field_validation(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="form_fieldtype.3x.html">form_fieldtype(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_hook.3x.html b/doc/html/man/form_hook.3x.html index 4845771f8112..899ce02d64ec 100644 --- a/doc/html/man/form_hook.3x.html +++ b/doc/html/man/form_hook.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_hook.3x,v 1.37 2024/03/16 15:35:01 tom Exp @ + * @Id: form_hook.3x,v 1.39 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_hook 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_hook 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_hook 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_hook 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_hook.3x.html">form_hook(3x)</A></STRONG> Library calls <STRONG><A HREF="form_hook.3x.html">form_hook(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>form_hook</STRONG> - set hooks for automatic invocation by applications @@ -78,7 +76,7 @@ </PRE><H3><a name="h3-field_init">field_init</a></H3><PRE> - returns the current field init hook, if any (<STRONG>NULL</STRONG> if there is no such + returns the current field init hook, if any (<EM>NULL</EM> if there is no such hook). @@ -88,7 +86,7 @@ </PRE><H3><a name="h3-field_term">field_term</a></H3><PRE> - returns the current field term hook, if any (<STRONG>NULL</STRONG> if there is no such + returns the current field term hook, if any (<EM>NULL</EM> if there is no such hook). @@ -98,7 +96,7 @@ </PRE><H3><a name="h3-form_init">form_init</a></H3><PRE> - returns the current form init hook, if any (<STRONG>NULL</STRONG> if there is no such + returns the current form init hook, if any (<EM>NULL</EM> if there is no such hook). @@ -108,12 +106,12 @@ </PRE><H3><a name="h3-form_term">form_term</a></H3><PRE> - returns the current form term hook, if any (<STRONG>NULL</STRONG> if there is no such + returns the current form term hook, if any (<EM>NULL</EM> if there is no such hook). </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Routines that return pointers return <STRONG>NULL</STRONG> on error. Other routines + Routines that return pointers return <EM>NULL</EM> on error. Other routines return one of the following: <STRONG>E_OK</STRONG> The routine succeeded. @@ -135,9 +133,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_hook.3x.html">form_hook(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="form_hook.3x.html">form_hook(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_new.3x.html b/doc/html/man/form_new.3x.html index 7a1877cad84d..78f7862d1647 100644 --- a/doc/html/man/form_new.3x.html +++ b/doc/html/man/form_new.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_new.3x,v 1.32 2024/03/16 15:35:01 tom Exp @ + * @Id: form_new.3x,v 1.34 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_new 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_new 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_new 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_new 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_new.3x.html">form_new(3x)</A></STRONG> Library calls <STRONG><A HREF="form_new.3x.html">form_new(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>new_form</STRONG>, <STRONG>free_form</STRONG> - create and destroy forms @@ -59,14 +57,14 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>new_form</STRONG> creates a new form connected to a specified field - pointer array (which must be <STRONG>NULL</STRONG>-terminated). + pointer array (which must be <EM>NULL</EM>-terminated). - The function <STRONG>free_form</STRONG> disconnects <EM>form</EM> from its field array and frees + The function <STRONG>free_form</STRONG> disconnects <EM>form</EM> from its field array and frees the storage allocated for the form. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The function <STRONG>new_form</STRONG> returns <STRONG>NULL</STRONG> on error. It sets <STRONG>errno</STRONG> according + The function <STRONG>new_form</STRONG> returns <EM>NULL</EM> on error. It sets <STRONG>errno</STRONG> according to the function's success: <STRONG>E_OK</STRONG> The routine succeeded. @@ -92,7 +90,7 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V forms library. They were not + These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions. @@ -104,9 +102,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_new.3x.html">form_new(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="form_new.3x.html">form_new(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_new_page.3x.html b/doc/html/man/form_new_page.3x.html index e8a18df4ff0f..5505e4a8f5a7 100644 --- a/doc/html/man/form_new_page.3x.html +++ b/doc/html/man/form_new_page.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_new_page 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_new_page 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_new_page 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_new_page 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_new_page.3x.html">form_new_page(3x)</A></STRONG> Library calls <STRONG><A HREF="form_new_page.3x.html">form_new_page(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_new_page</STRONG>, <STRONG>new_page</STRONG> - form pagination functions @@ -87,12 +85,10 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "form_" for detailed + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "form_" for detailed descriptions of the entry points. - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_new_page.3x.html">form_new_page(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="form_new_page.3x.html">form_new_page(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_opts.3x.html b/doc/html/man/form_opts.3x.html index 63a9437fc873..8a9f4c23acbb 100644 --- a/doc/html/man/form_opts.3x.html +++ b/doc/html/man/form_opts.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2015 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_opts.3x,v 1.34 2024/03/16 15:35:01 tom Exp @ + * @Id: form_opts.3x,v 1.37 2025/01/19 00:51:10 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_opts 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_opts 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_opts 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_opts 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_opts.3x.html">form_opts(3x)</A></STRONG> Library calls <STRONG><A HREF="form_opts.3x.html">form_opts(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_form_opts</STRONG>, <STRONG>form_opts_on</STRONG>, <STRONG>form_opts_off</STRONG>, <STRONG>form_opts</STRONG> - set and get form options @@ -63,7 +61,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>set_form_opts</STRONG> sets all the given form's option bits (form - option bits may be logically-OR'ed together). + option bits may be logically "or"-ed together). The function <STRONG>form_opts_on</STRONG> turns on the given option bits, and leaves others alone. @@ -106,9 +104,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_opts.3x.html">form_opts(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="form_opts.3x.html">form_opts(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_page.3x.html b/doc/html/man/form_page.3x.html index b882db2beb49..89f8687288e0 100644 --- a/doc/html/man/form_page.3x.html +++ b/doc/html/man/form_page.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_page.3x,v 1.37 2024/03/16 15:35:01 tom Exp @ + * @Id: form_page.3x,v 1.39 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_page 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_page 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_page 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_page 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_page.3x.html">form_page(3x)</A></STRONG> Library calls <STRONG><A HREF="form_page.3x.html">form_page(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>form_page</STRONG> - set and get form page number @@ -70,7 +68,7 @@ The function <STRONG>unfocus_current_field</STRONG> removes the focus from the current field of the form. In such state, inquiries via <STRONG>current_field</STRONG> shall - return a NULL pointer. + return a <EM>NULL</EM> pointer. The function <STRONG>set_form_page</STRONG> sets the form's page number (goes to page <EM>n</EM> of the form). @@ -118,9 +116,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_page.3x.html">form_page(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="form_page.3x.html">form_page(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_post.3x.html b/doc/html/man/form_post.3x.html index 9f97d3e5e8da..de92b31dc2f2 100644 --- a/doc/html/man/form_post.3x.html +++ b/doc/html/man/form_post.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_post 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_post 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_post 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_post 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_post.3x.html">form_post(3x)</A></STRONG> Library calls <STRONG><A HREF="form_post.3x.html">form_post(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>post_form</STRONG>, <STRONG>unpost_form</STRONG> - write or erase forms from associated subwindows @@ -60,7 +58,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>post_form</STRONG> displays a form to its associated subwindow. To - trigger physical display of the subwindow, use <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> or some + trigger physical display of the subwindow, use <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> or some equivalent <STRONG>curses</STRONG> routine (the implicit <STRONG>doupdate</STRONG> triggered by an <STRONG>curses</STRONG> input request will do). @@ -107,9 +105,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_post.3x.html">form_post(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="form_post.3x.html">form_post(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_requestname.3x.html b/doc/html/man/form_requestname.3x.html index ecb5992d428a..b85a5d40d913 100644 --- a/doc/html/man/form_requestname.3x.html +++ b/doc/html/man/form_requestname.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_requestname.3x,v 1.35 2024/03/16 15:35:01 tom Exp @ + * @Id: form_requestname.3x,v 1.37 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_requestname 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_requestname 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_requestname 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_requestname 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_requestname.3x.html">form_requestname(3x)</A></STRONG> Library calls <STRONG><A HREF="form_requestname.3x.html">form_requestname(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>form_request_by_name</STRONG>, <STRONG>form_request_name</STRONG> - handle printable form request names @@ -59,22 +57,22 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The function <STRONG>form_request_name</STRONG> returns the printable name of a form - request code. The function <STRONG>form_request_by_name</STRONG> searches in the name- - table for a request with the given name and returns its request code. + The function <STRONG>form_request_name</STRONG> returns the printable name of a form + request code. The function <STRONG>form_request_by_name</STRONG> searches in the name- + table for a request with the given name and returns its request code. Otherwise E_NO_MATCH is returned. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - <STRONG>form_request_name</STRONG> returns <STRONG>NULL</STRONG> on error and sets <STRONG>errno</STRONG> to + <STRONG>form_request_name</STRONG> returns <EM>NULL</EM> on error and sets <STRONG>errno</STRONG> to <STRONG>E_BAD_ARGUMENT</STRONG>. - <STRONG>form_request_by_name</STRONG> returns <STRONG>E_NO_MATCH</STRONG> on error. It does not set + <STRONG>form_request_by_name</STRONG> returns <STRONG>E_NO_MATCH</STRONG> on error. It does not set <STRONG>errno</STRONG>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines are specific to <EM>ncurses</EM>. They were not supported on + These routines are specific to <EM>ncurses</EM>. They were not supported on Version 7, BSD or System V implementations. It is recommended that any code depending on them be conditioned using NCURSES_VERSION. @@ -87,9 +85,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_requestname.3x.html">form_requestname(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="form_requestname.3x.html">form_requestname(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_userptr.3x.html b/doc/html/man/form_userptr.3x.html index db79de2022cb..d588598f5804 100644 --- a/doc/html/man/form_userptr.3x.html +++ b/doc/html/man/form_userptr.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_userptr.3x,v 1.36 2024/03/16 15:35:01 tom Exp @ + * @Id: form_userptr.3x,v 1.38 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_userptr 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_userptr 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_userptr 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_userptr 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_userptr.3x.html">form_userptr(3x)</A></STRONG> Library calls <STRONG><A HREF="form_userptr.3x.html">form_userptr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_form_userptr</STRONG>, <STRONG>form_userptr</STRONG> - associate application data with a form item @@ -59,20 +57,20 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - Every form and every form item has a field that can be used to hold - application-specific data (that is, the form-driver code leaves it + Every form and every form item has a field that can be used to hold + application-specific data (that is, the form-driver code leaves it alone). These functions get and set the form user pointer field. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The function <STRONG>form_userptr</STRONG> returns a pointer (which may be <STRONG>NULL</STRONG>). It + The function <STRONG>form_userptr</STRONG> returns a pointer (which may be <EM>NULL</EM>). It does not set <STRONG>errno</STRONG>. The function <STRONG>set_form_userptr</STRONG> returns <STRONG>E_OK</STRONG> (success). </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V forms library. They were not + These routines emulate the System V forms library. They were not supported on Version 7 or BSD versions. The user pointer is a void pointer. We chose not to leave it as a char @@ -87,9 +85,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_userptr.3x.html">form_userptr(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="form_userptr.3x.html">form_userptr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_variables.3x.html b/doc/html/man/form_variables.3x.html index 68c8e5635c55..cd08872f7a5c 100644 --- a/doc/html/man/form_variables.3x.html +++ b/doc/html/man/form_variables.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_variables 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_variables 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_variables 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_variables 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_variables.3x.html">form_variables(3x)</A></STRONG> Library calls <STRONG><A HREF="form_variables.3x.html">form_variables(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>TYPE_ALNUM</STRONG>, <STRONG>TYPE_ALPHA</STRONG>, <STRONG>TYPE_ENUM</STRONG>, <STRONG>TYPE_INTEGER</STRONG>, <STRONG>TYPE_IPV4</STRONG>, <STRONG>TYPE_NUMERIC</STRONG>, <STRONG>TYPE_REGEXP</STRONG> - form system global variables @@ -106,9 +104,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_variables.3x.html">form_variables(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="form_variables.3x.html">form_variables(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/form_win.3x.html b/doc/html/man/form_win.3x.html index 976ef2714ed0..da9bbc126b97 100644 --- a/doc/html/man/form_win.3x.html +++ b/doc/html/man/form_win.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: form_win.3x,v 1.35 2024/03/16 15:35:01 tom Exp @ + * @Id: form_win.3x,v 1.37 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>form_win 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>form_win 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">form_win 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">form_win 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="form_win.3x.html">form_win(3x)</A></STRONG> Library calls <STRONG><A HREF="form_win.3x.html">form_win(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>form_win</STRONG> - make and break form window and subwindow associations @@ -72,8 +70,8 @@ necessary to set either window; by default, the driver code uses <STRONG>stdscr</STRONG> for both. - In the <STRONG>set_</STRONG> functions, window argument of <STRONG>NULL</STRONG> is treated as though it - were <STRONG>stsdcr</STRONG>. A form argument of <STRONG>NULL</STRONG> is treated as a request to change + In the <STRONG>set_</STRONG> functions, window argument of <EM>NULL</EM> is treated as though it + were <STRONG>stsdcr</STRONG>. A form argument of <EM>NULL</EM> is treated as a request to change the system default form window or subwindow. The function <STRONG>scale_form</STRONG> returns the minimum size required for the @@ -81,7 +79,7 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Routines that return pointers return <STRONG>NULL</STRONG> on error. Routines that + Routines that return pointers return <EM>NULL</EM> on error. Routines that return an integer return one of the following error codes: <STRONG>E_OK</STRONG> The routine succeeded. @@ -112,9 +110,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="form_win.3x.html">form_win(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="form_win.3x.html">form_win(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/index.html b/doc/html/man/index.html index 07d986b6b166..e50cd2f98776 100644 --- a/doc/html/man/index.html +++ b/doc/html/man/index.html @@ -1,7 +1,7 @@ <!-- - $Id: index.html,v 1.12 2020/02/02 23:34:34 tom Exp $ + $Id: index.html,v 1.13 2024/05/25 22:27:27 tom Exp $ **************************************************************************** - * Copyright 2019,2020 Thomas E. Dickey * + * Copyright 2019-2020,2024 Thomas E. Dickey * * Copyright 2001-2013,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -30,22 +30,18 @@ **************************************************************************** --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> - <html> <head> <meta name="generator" content= - "HTML Tidy for Linux (vers 25 March 2009), see www.w3.org"> - + "HTML Tidy for HTML5 for Linux version 5.6.0"> <title>NCURSES – Manual Pages</title> <link rel="author" href="mailto:dickey@invisible-island.net"> <meta http-equiv="Content-Type" content= "text/html; charset=us-ascii"> </head> - <body> <ul> <li>Programs: - <ul> <li><a href="captoinfo.1m.html">captoinfo – convert a termcap description into a terminfo description</a></li> @@ -59,64 +55,69 @@ <li><a href="infotocap.1m.html">infotocap – convert a terminfo description into a termcap description</a></li> - <li><a href="tabs.1.html">tabs – set tabs on a - terminal</a></li> + <li><a href="tabs.1.html">tabs – set terminal tab + stops</a></li> - <li><a href="tic.1m.html">tic – the terminfo - entry-description compiler</a></li> + <li><a href="tic.1m.html">tic – compile terminal + descriptions for terminfo or termcap</a></li> - <li><a href="toe.1m.html">toe – table of (terminfo) - entries</a></li> + <li><a href="toe.1m.html">toe – list table of entries + of terminfo terminal types</a></li> <li><a href="tput.1.html">tput – initialize a - terminal or query terminfo database</a></li> + terminal, exercise its capabilities, or query terminfo + database</a></li> - <li><a href="tset.1.html">tset – terminal - initialization</a></li> + <li><a href="tset.1.html">tset – initialize or reset + terminal state</a></li> </ul> </li> <li>Scripts: - <ul> <li><a href= "adacurses6-config.1.html">adacurses*-config</a> – - helper script for AdaCurses libraries</li> + configuration helper for AdaCurses libraries</li> <li><a href="ncurses6-config.1.html">ncurses*-config</a> - – helper script for ncurses libraries</li> + – configuration helper for ncurses libraries</li> </ul> </li> <li>Libraries: - <ul> - <li><a href="ncurses.3x.html">ncurses – CRT screen - handling and optimization package</a></li> + <li><a href="ncurses.3x.html">ncurses – + character-cell terminal interface with optimized output</a></li> - <li><a href="panel.3x.html">panel – panel stack - extension for curses</a></li> + <li><a href="panel.3x.html">panel – manage + overlapping curses windows</a></li> - <li><a href="form.3x.html">form – curses extension - for programming forms</a></li> + <li><a href="form.3x.html">form – present + user-fillable forms in curses windows</a></li> - <li><a href="menu.3x.html">menu – curses extension - for programming menus</a></li> + <li><a href="menu.3x.html">menu – present menus in + curses windows</a></li> </ul> </li> <li>File formats: - <ul> <li><a href="terminfo.5.html">terminfo – terminal - capability data base</a></li> + capability database</a></li> - <li><a href="term.5.html">term – format of compiled - term file.</a></li> + <li><a href="term.5.html">term – compiled terminfo + terminal description</a></li> - <li><a href="scr_dump.5.html">scr_dump – format of - curses screen dumps.</a></li> + <li><a href="scr_dump.5.html">scr_dump – curses + screen dump</a></li> + <li><a href="user_caps.5.html">user_caps – + user-defined terminfo capability format</a></li> + </ul> + </li> + + <li>Other information: + <ul> <li><a href="term.7.html">term – conventions for naming terminal types</a></li> </ul> diff --git a/doc/html/man/infocmp.1m.html b/doc/html/man/infocmp.1m.html index 44cb12fb7122..b8fcd0386962 100644 --- a/doc/html/man/infocmp.1m.html +++ b/doc/html/man/infocmp.1m.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2017,2018 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,91 +28,52 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: infocmp.1m,v 1.109 2024/03/16 15:35:01 tom Exp @ + * @Id: infocmp.1m,v 1.128 2025/11/12 00:52:57 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>infocmp 1m 2024-03-16 ncurses 6.5 User commands</TITLE> +<TITLE>infocmp 1m 2025-11-11 ncurses 6.6 User commands</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">infocmp 1m 2024-03-16 ncurses 6.5 User commands</H1> +<H1 class="no-header">infocmp 1m 2025-11-11 ncurses 6.6 User commands</H1> <PRE> <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG> User commands <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>infocmp</STRONG> - compare or print out <EM>terminfo</EM> descriptions </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> - <STRONG>infocmp</STRONG> [<STRONG>-1cCdDeEFgGiIKlLnpqrtTuUVWx</STRONG>] - [<STRONG>-v</STRONG> <EM>n</EM>] [<STRONG>-s</STRONG> <STRONG>d</STRONG>| <STRONG>i</STRONG>| <STRONG>l</STRONG>| <STRONG>c</STRONG>] [<STRONG>-Q</STRONG> <EM>n</EM>] [<STRONG>-R</STRONG> <STRONG>subset</STRONG>] - [<STRONG>-w</STRONG> <EM>width</EM>] [<STRONG>-A</STRONG> <EM>directory</EM>] [<STRONG>-B</STRONG> <EM>directory</EM>] - [<EM>terminal-type</EM> ...] - - -</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - <STRONG>infocmp</STRONG> can be used to compare a binary <STRONG>terminfo</STRONG> entry with other - terminfo entries, rewrite a <STRONG>terminfo</STRONG> description to take advantage of - the <STRONG>use=</STRONG> terminfo field, or print out a <STRONG>terminfo</STRONG> description from the - binary file (<STRONG>term</STRONG>) in a variety of formats. In all cases, the Boolean - fields will be printed first, followed by the numeric fields, followed - by the string fields. -</PRE><H3><a name="h3-Default-Options">Default Options</a></H3><PRE> - If no options are specified and zero or one <EM>terminal-types</EM> are - specified, the <STRONG>-I</STRONG> option will be assumed. If more than one <EM>terminal-</EM> - <EM>type</EM> is specified, the <STRONG>-d</STRONG> option will be assumed. - + <STRONG>infocmp</STRONG> [<STRONG>-1cCdDeEFgGiIKlLnpqrtTuUVWx]</STRONG> [<STRONG>-A</STRONG> <EM>directory</EM>] [<STRONG>-B</STRONG> <EM>directory</EM>] + [<STRONG>-Q</STRONG> <EM>encoding</EM>] [<STRONG>-R</STRONG> <EM>subset</EM>] [<STRONG>-s</STRONG> <EM>key</EM>] [<STRONG>-v</STRONG> <EM>level</EM>] [<STRONG>-w</STRONG> <EM>width</EM>] + [<EM>terminal-type</EM> ... ] -</PRE><H3><a name="h3-Comparison-Options_d_c_n_">Comparison Options [-d] [-c] [-n]</a></H3><PRE> - <STRONG>infocmp</STRONG> compares the <STRONG>terminfo</STRONG> description of the first terminal - <EM>terminal-type</EM> with each of the descriptions given by the entries for - the other terminal's <EM>terminal-types</EM>. If a capability is defined for - only one of the terminals, the value returned depends on the type of - the capability: - <STRONG>o</STRONG> <STRONG>F</STRONG> for missing Boolean variables - - <STRONG>o</STRONG> <STRONG>NULL</STRONG> for missing integer or string variables - - Use the <STRONG>-q</STRONG> option to show the distinction between <EM>absent</EM> and <EM>cancelled</EM> +</PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> + <STRONG>infocmp</STRONG> reports a human-readable terminal type description from a + compiled entry in the <EM>terminfo</EM> database in a variety of selectable + formats, compares such entries to each other, and rewrites an entry to + replace "<STRONG>use</STRONG>" expressions with the content of other entries by + reference. A <EM>terminfo</EM> <EM>entry</EM> comprises a list of one or more terminal + type identifiers, a human-readable description of the terminal type, + and a list of terminal <EM>capabilities</EM> that characterize its programming + interface. In all cases, the program reports Boolean-valued + capabilities first, followed by numeric ones, and then string-valued capabilities. - These options produce a list which you can use to compare two or more - terminal descriptions: - - <STRONG>-d</STRONG> produces a list of each capability that is <EM>different</EM> between two - entries. Each item in the list shows ":" after the capability - name, followed by the capability values, separated by a comma. - - <STRONG>-c</STRONG> produces a list of each capability that is <EM>common</EM> between two or - more entries. Missing capabilities are ignored. Each item in the - list shows "=" after the capability name, followed by the - capability value. - - The <STRONG>-u</STRONG> option provides a related output, showing the first - terminal description rewritten to use the second as a building - block via the "use=" clause. - <STRONG>-n</STRONG> produces a list of each capability that is in <EM>none</EM> of the given - entries. Each item in the list shows "!" before the capability - name. - - Normally only the conventional capabilities are shown. Use the <STRONG>-x</STRONG> - option to add the BSD-compatibility capabilities (names prefixed - with "OT"). - - If no <EM>terminal-types</EM> are given, <STRONG>infocmp</STRONG> uses the environment - variable <EM>TERM</EM> for each of the <EM>terminal-types</EM>. +</PRE><H3><a name="h3-Default-Options">Default Options</a></H3><PRE> + If no options are specified and zero or one <EM>terminal-types</EM> is + specified, <STRONG>infocmp</STRONG> assumes the <STRONG>-I</STRONG> option. If more than one is + specified, the program assumes the <STRONG>-d</STRONG> option. </PRE><H3><a name="h3-Source-Listing-Options_I_L_C_r_">Source Listing Options [-I] [-L] [-C] [-r]</a></H3><PRE> @@ -135,8 +96,8 @@ output and commented out. These should be edited by hand. For best results when converting to <STRONG>termcap</STRONG> format, you should use both - <STRONG>-C</STRONG> and <STRONG>-r</STRONG>. Normally a termcap description is limited to 1023 bytes. - <STRONG>infocmp</STRONG> trims away less essential parts to make it fit. If you are + <STRONG>-C</STRONG> and <STRONG>-r</STRONG>. Normally a termcap description is limited to 1023 bytes. + <STRONG>infocmp</STRONG> trims away less essential parts to make it fit. If you are converting to one of the (rare) termcap implementations which accept an unlimited size of termcap, you may want to add the <STRONG>-T</STRONG> option. More often however, you must help the termcap implementation, and trim @@ -147,9 +108,9 @@ Mandatory padding (padding information with a trailing "/") will become optional. - All <STRONG>termcap</STRONG> variables no longer supported by <STRONG>terminfo</STRONG>, but which are - derivable from other <STRONG>terminfo</STRONG> variables, will be output. Not all - <STRONG>terminfo</STRONG> capabilities will be translated; only those variables which + All <STRONG>termcap</STRONG> variables no longer supported by <STRONG>terminfo</STRONG>, but which are + derivable from other <STRONG>terminfo</STRONG> variables, will be output. Not all + <STRONG>terminfo</STRONG> capabilities will be translated; only those variables which were part of <STRONG>termcap</STRONG> will normally be output. Specifying the <STRONG>-r</STRONG> option will take off this restriction, allowing all capabilities to be output in <EM>termcap</EM> form. Normally you would use both the <STRONG>-C</STRONG> and <STRONG>-r</STRONG> options. @@ -162,10 +123,10 @@ supported. Because <STRONG>termcap</STRONG> strings are not as flexible, it is not always possible to convert a <STRONG>terminfo</STRONG> string capability into an equivalent <STRONG>termcap</STRONG> format. A subsequent conversion of the <STRONG>termcap</STRONG> file - back into <STRONG>terminfo</STRONG> format will not necessarily reproduce the original + back into <STRONG>terminfo</STRONG> format will not necessarily reproduce the original <STRONG>terminfo</STRONG> source. - Some common <STRONG>terminfo</STRONG> parameter sequences, their <STRONG>termcap</STRONG> equivalents, + Some common <STRONG>terminfo</STRONG> parameter sequences, their <STRONG>termcap</STRONG> equivalents, and some terminal types which commonly have such sequences, are: <STRONG><EM>terminfo</EM></STRONG> <STRONG><EM>termcap</EM></STRONG> Terminal Types @@ -178,8 +139,48 @@ <STRONG>%p2</STRONG>...<STRONG>%p1</STRONG> <STRONG>%r</STRONG> hpgeneric +</PRE><H3><a name="h3-Entry-Comparison-Options_d_c_n_">Entry Comparison Options [-d] [-c] [-n]</a></H3><PRE> + Given <STRONG>-c</STRONG>, <STRONG>-d</STRONG>, or <STRONG>-n</STRONG>, <STRONG>infocmp</STRONG> compares the <EM>terminfo</EM> description of the + first specified <EM>terminal-type</EM> with those of each of the subsequent + operands. If fewer <EM>terminal-types</EM> than required are specified, <STRONG>infocmp</STRONG> + uses the environment variable <EM>TERM</EM> in their place. + + If a capability is defined for only one terminal type, the value + reported depends on the capability's type: + + <STRONG>o</STRONG> <STRONG>F</STRONG> for missing Boolean variables + + <STRONG>o</STRONG> <STRONG>NULL</STRONG> for missing integer or string variables + + The <STRONG>-c</STRONG> and <STRONG>-d</STRONG> options report string capability values between "'" + characters. Use the <STRONG>-q</STRONG> option to distinguish <EM>absent</EM> and <EM>canceled</EM> + capabilities; see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. + + The comparison option selects the form of report. + + <STRONG>-d</STRONG> lists each capability that <EM>differs</EM> between two entries. Each + capability name is followed by ":" and comma-separated capability + values, then a period. + + <STRONG>-c</STRONG> lists each capability that two entries have in <EM>common</EM>. <STRONG>infocmp</STRONG> + ignores capabilities missing from either entry. Each capability + name is followed by "=", a space, and the capability value, then a + period. + + If the <STRONG>-u</STRONG> option is further specified, <STRONG>infocmp</STRONG> rewrites the + description of the first type employing "use=" syntax to use the + second as a building block. + + <STRONG>-n</STRONG> lists capabilities that are in <EM>none</EM> of the given entries. Each + capability name is preceded by "!" and followed by a period. + + Normally only conventional capabilities are shown. Use the <STRONG>-x</STRONG> + option to add BSD-compatibility capabilities (names prefixed with + "OT"). + + </PRE><H3><a name="h3-Use_Option_u_">Use= Option [-u]</a></H3><PRE> - The <STRONG>-u</STRONG> option produces a <STRONG>terminfo</STRONG> source description of the first + The <STRONG>-u</STRONG> option produces a <STRONG>terminfo</STRONG> source description of the first terminal <EM>terminal-type</EM> which is relative to the sum of the descriptions given by the entries for the other <EM>terminal-types</EM>. It does this by analyzing the differences between the first <EM>terminal-types</EM> and the @@ -192,11 +193,11 @@ relative to the other. A capability will be printed with an at-sign (@) if it no longer exists - in the first <EM>terminal-type</EM>, but one of the other <EM>terminal-type</EM> entries - contains a value for it. A capability's value will be printed if the - value in the first <EM>terminal-type</EM> is not found in any of the other - <EM>terminal-type</EM> entries, or if the first of the other <EM>terminal-type</EM> - entries that has this capability gives a different value for the + in the first <EM>terminal-type</EM>, but one of the other <EM>terminal-type</EM> entries + contains a value for it. A capability's value will be printed if the + value in the first <EM>terminal-type</EM> is not found in any of the other + <EM>terminal-type</EM> entries, or if the first of the other <EM>terminal-type</EM> + entries that has this capability gives a different value for the capability than that in the first <EM>terminal-type</EM>. The order of the other <EM>terminal-type</EM> entries is significant. Since the @@ -207,33 +208,34 @@ between the other <EM>terminal-type</EM> entries as they are found. Alternatively, specifying a capability <EM>after</EM> a <STRONG>use=</STRONG> entry that contains - that capability will cause the second specification to be ignored. - Using <STRONG>infocmp</STRONG> to recreate a description can be a useful check to make - sure that everything was specified correctly in the original source + that capability will cause the second specification to be ignored. + Using <STRONG>infocmp</STRONG> to recreate a description can be a useful check to make + sure that everything was specified correctly in the original source description. - Another error that does not cause incorrect compiled files, but will - slow down the compilation time, is specifying extra <STRONG>use=</STRONG> fields that + Another error that does not cause incorrect compiled files, but will + slow down the compilation time, is specifying extra <STRONG>use=</STRONG> fields that are superfluous. <STRONG>infocmp</STRONG> will flag any other <EM>terminal-type</EM> <EM>use=</EM> fields that were not needed. - <STRONG>Changing</STRONG> <STRONG>Databases</STRONG> <STRONG>[-A</STRONG> <EM>directory</EM>] [-B <EM>directory</EM>] + +</PRE><H3><a name="h3-Changing-Databases_A-directory_B-directory_">Changing Databases [-A directory] [-B directory]</a></H3><PRE> Like other <EM>ncurses</EM> utilities, <STRONG>infocmp</STRONG> looks for the terminal descriptions in several places. You can use the <EM>TERMINFO</EM> and <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> environment variables to override the compiled-in default - list of places to search. See <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, as well as the <EM>Fetching</EM> + list of places to search. See <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, as well as the <EM>Fetching</EM> <EM>Compiled</EM> <EM>Descriptions</EM> section in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. - You can also use the options <STRONG>-A</STRONG> and <STRONG>-B</STRONG> to override the list of places + You can also use the options <STRONG>-A</STRONG> and <STRONG>-B</STRONG> to override the list of places to search when comparing terminal descriptions: <STRONG>o</STRONG> The <STRONG>-A</STRONG> option sets the location for the first <EM>terminal-type</EM> <STRONG>o</STRONG> The <STRONG>-B</STRONG> option sets the location for the other <EM>terminal-types</EM>. - Using these options, it is possible to compare descriptions for a - terminal with the same name located in two different databases. For - instance, you can use this feature for comparing descriptions for the + Using these options, it is possible to compare descriptions for a + terminal with the same name located in two different databases. For + instance, you can use this feature for comparing descriptions for the same terminal created by different people. @@ -251,17 +253,17 @@ <STRONG>-D</STRONG> tells <STRONG>infocmp</STRONG> to print the database locations that it knows about, and exit. - <STRONG>-E</STRONG> Dump the capabilities of the given terminal as tables, needed in - the C initializer for a TERMTYPE structure (the terminal - capability structure in the <STRONG><term.h></STRONG>). This option is useful for - preparing versions of the curses library hardwired for a given - terminal type. The tables are all declared static, and are named - according to the type and the name of the corresponding terminal + <STRONG>-E</STRONG> Dump the capabilities of the given terminal as tables, needed in + the C initializer for a TERMTYPE structure (the terminal + capability structure in the <STRONG><term.h></STRONG>). This option is useful for + preparing versions of the curses library hardwired for a given + terminal type. The tables are all declared static, and are named + according to the type and the name of the corresponding terminal entry. - Before <EM>ncurses</EM> 5.0, the split between the <STRONG>-e</STRONG> and <STRONG>-E</STRONG> options was - not needed; but support for extended names required making the - arrays of terminal capabilities separate from the TERMTYPE + Before <EM>ncurses</EM> 5.0, the split between the <STRONG>-e</STRONG> and <STRONG>-E</STRONG> options was + not needed; but support for extended names required making the + arrays of terminal capabilities separate from the TERMTYPE structure. <STRONG>-e</STRONG> Dump the capabilities of the given terminal as a C initializer for @@ -270,31 +272,31 @@ curses library hardwired for a given terminal type. <STRONG>-F</STRONG> compare terminfo files. This assumes that two following arguments - are filenames. The files are searched for pairwise matches - between entries, with two entries considered to match if any of - their names do. The report printed to standard output lists - entries with no matches in the other file, and entries with more - than one match. For entries with exactly one match it includes a - difference report. Normally, to reduce the volume of the report, - use references are not resolved before looking for differences, + are filenames. The files are searched for pairwise matches + between entries, with two entries considered to match if any of + their names do. The report printed to standard output lists + entries with no matches in the other file, and entries with more + than one match. For entries with exactly one match it includes a + difference report. Normally, to reduce the volume of the report, + use references are not resolved before looking for differences, but resolution can be forced by also specifying <STRONG>-r</STRONG>. - <STRONG>-f</STRONG> Display complex terminfo strings which contain if/then/else/endif + <STRONG>-f</STRONG> Display complex terminfo strings which contain if/then/else/endif expressions indented for readability. - <STRONG>-G</STRONG> Display constant literals in decimal form rather than their + <STRONG>-G</STRONG> Display constant literals in decimal form rather than their character equivalents. - <STRONG>-g</STRONG> Display constant character literals in quoted form rather than + <STRONG>-g</STRONG> Display constant character literals in quoted form rather than their decimal equivalents. - <STRONG>-i</STRONG> Analyze the initialization (<STRONG>is1</STRONG>, <STRONG>is2</STRONG>, <STRONG>is3</STRONG>), and reset (<STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>, - <STRONG>rs3</STRONG>), strings in the entry, as well as those used for - starting/stopping cursor-positioning mode (<STRONG>smcup</STRONG>, <STRONG>rmcup</STRONG>) as well + <STRONG>-i</STRONG> Analyze the initialization (<STRONG>is1</STRONG>, <STRONG>is2</STRONG>, <STRONG>is3</STRONG>), and reset (<STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>, + <STRONG>rs3</STRONG>), strings in the entry, as well as those used for + starting/stopping cursor-positioning mode (<STRONG>smcup</STRONG>, <STRONG>rmcup</STRONG>) as well as starting/stopping keymap mode (<STRONG>smkx</STRONG>, <STRONG>rmkx</STRONG>). - For each string, the code tries to analyze it into actions in - terms of the other capabilities in the entry, certain X3.64/ISO + For each string, the code tries to analyze it into actions in + terms of the other capabilities in the entry, certain X3.64/ISO 6429/ECMA-48 capabilities, and certain DEC VT-series private modes (the set of recognized special sequences has been selected for completeness over the existing terminfo database). Each report @@ -313,7 +315,6 @@ LL home-down RSR reset scroll region ----------------------------------------- - DECSTR soft reset (VT320) S7C1T 7-bit controls (VT220) ----------------------------------------- @@ -378,41 +379,41 @@ and using "-" for absent capabilities, "@" for canceled rather than "NULL". - <STRONG>o</STRONG> However, show differences between absent and cancelled + <STRONG>o</STRONG> However, show differences between absent and canceled capabilities. <STRONG>o</STRONG> Omit the "Reconstructed from" comment for source listings. <STRONG>-R</STRONG><EM>subset</EM> - Restrict output to a given subset. This option is for use with - archaic versions of terminfo like those on SVr1, Ultrix, or HP-UX - that do not support the full set of SVR4/XSI Curses terminfo; and - variants such as AIX that have their own extensions incompatible + Restrict output to a given subset. This option is for use with + archaic versions of terminfo like those on SVr1, Ultrix, or HP-UX + that do not support the full set of SVR4/XSI Curses terminfo; and + variants such as AIX that have their own extensions incompatible with SVr4/XSI. - <STRONG>o</STRONG> Available terminfo subsets are "SVr1", "Ultrix", "HP", and + <STRONG>o</STRONG> Available terminfo subsets are "SVr1", "Ultrix", "HP", and "AIX"; see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for details. - <STRONG>o</STRONG> You can also choose the subset "BSD" which selects only + <STRONG>o</STRONG> You can also choose the subset "BSD" which selects only capabilities with termcap equivalents recognized by 4.4BSD. - <STRONG>o</STRONG> If you select any other value for <STRONG>-R</STRONG>, it is the same as no + <STRONG>o</STRONG> If you select any other value for <STRONG>-R</STRONG>, it is the same as no subset, i.e., all capabilities are used. - A few options override the subset selected with <STRONG>-R</STRONG>, if they are + A few options override the subset selected with <STRONG>-R</STRONG>, if they are processed later in the command parameters: - <STRONG>-C</STRONG> sets the "BSD" subset as a side-effect. + <STRONG>-C</STRONG> sets the "BSD" subset as a side effect. <STRONG>-I</STRONG> sets the subset to all capabilities. <STRONG>-r</STRONG> sets the subset to all capabilities. <STRONG>-s</STRONG> <EM>[d|i|l|c]</EM> - The <STRONG>-s</STRONG> option sorts the fields within each type according to the + The <STRONG>-s</STRONG> option sorts the fields within each type according to the argument below: - <STRONG>d</STRONG> leave fields in the order that they are stored in the + <STRONG>d</STRONG> leave fields in the order that they are stored in the <EM>terminfo</EM> database. <STRONG>i</STRONG> sort by <EM>terminfo</EM> name. @@ -421,24 +422,24 @@ <STRONG>c</STRONG> sort by the <EM>termcap</EM> name. - If the <STRONG>-s</STRONG> option is not given, the fields printed out will be - sorted alphabetically by the <STRONG>terminfo</STRONG> name within each type, - except in the case of the <STRONG>-C</STRONG> or the <STRONG>-L</STRONG> options, which cause the - sorting to be done by the <STRONG>termcap</STRONG> name or the long C variable + If the <STRONG>-s</STRONG> option is not given, the fields printed out will be + sorted alphabetically by the <STRONG>terminfo</STRONG> name within each type, + except in the case of the <STRONG>-C</STRONG> or the <STRONG>-L</STRONG> options, which cause the + sorting to be done by the <STRONG>termcap</STRONG> name or the long C variable name, respectively. - <STRONG>-T</STRONG> eliminates size-restrictions on the generated text. This is + <STRONG>-T</STRONG> eliminates size-restrictions on the generated text. This is mainly useful for testing and analysis, since the compiled descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). - <STRONG>-t</STRONG> tells <STRONG>tic</STRONG> to discard commented-out capabilities. Normally when - translating from terminfo to termcap, untranslatable capabilities + <STRONG>-t</STRONG> tells <STRONG>tic</STRONG> to discard commented-out capabilities. Normally when + translating from terminfo to termcap, untranslatable capabilities are commented-out. - <STRONG>-U</STRONG> tells <STRONG>infocmp</STRONG> to not post-process the data after parsing the + <STRONG>-U</STRONG> tells <STRONG>infocmp</STRONG> to not post-process the data after parsing the source file. This feature helps when comparing the actual - contents of two source files, since it excludes the inferences + contents of two source files, since it excludes the inferences that <STRONG>infocmp</STRONG> makes to fill in missing data. <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> which was used in this program, and @@ -449,10 +450,10 @@ The optional parameter <EM>n</EM> is a number from 1 to 10, inclusive, indicating the desired level of detail of information. If <EM>ncurses</EM> - is built without tracing support, the optional parameter is + is built without tracing support, the optional parameter is ignored. - <STRONG>-W</STRONG> By itself, the <STRONG>-w</STRONG> option will not force long strings to be + <STRONG>-W</STRONG> By itself, the <STRONG>-w</STRONG> option will not force long strings to be wrapped. Use the <STRONG>-W</STRONG> option to do this. <STRONG>-w</STRONG> <EM>width</EM> @@ -469,27 +470,26 @@ </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - The <STRONG>-0</STRONG>, <STRONG>-1</STRONG>, <STRONG>-E</STRONG>, <STRONG>-F</STRONG>, <STRONG>-G</STRONG>, <STRONG>-Q</STRONG>, <STRONG>-R</STRONG>, <STRONG>-T</STRONG>, <STRONG>-V</STRONG>, <STRONG>-a</STRONG>, <STRONG>-e</STRONG>, <STRONG>-f</STRONG>, <STRONG>-g</STRONG>, <STRONG>-i</STRONG>, <STRONG>-l</STRONG>, <STRONG>-p</STRONG>, <STRONG>-q</STRONG> - and <STRONG>-t</STRONG> options are not supported in SVr4 curses. + The <STRONG>-0</STRONG>, <STRONG>-1</STRONG>, <STRONG>-a</STRONG>, <STRONG>-e</STRONG>, <STRONG>-E</STRONG>, <STRONG>-f</STRONG>, <STRONG>-F</STRONG>, <STRONG>-g</STRONG>, <STRONG>-G</STRONG>, <STRONG>-i</STRONG>, <STRONG>-l</STRONG>, <STRONG>-p</STRONG>, <STRONG>-q</STRONG>, <STRONG>-Q</STRONG>, <STRONG>-R</STRONG>, <STRONG>-t</STRONG>, <STRONG>-T</STRONG>, + and <STRONG>-V</STRONG> options are <EM>ncurses</EM> extensions. - SVr4 infocmp does not distinguish between absent and cancelled - capabilities. Also, it shows missing integer capabilities as <STRONG>-1</STRONG> (the - internal value used to represent missing integers). This - implementation shows those as "NULL", for consistency with missing - strings. - The <STRONG>-r</STRONG> option's notion of "termcap" capabilities is System V Release - 4's. Actual BSD curses versions will have a more restricted set. To - see only the 4.4BSD set, use <STRONG>-r</STRONG> <STRONG>-RBSD</STRONG>. +</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> + X/Open Curses Issue 7 (2009) specifies <EM>infocmp</EM>. It does not mention + options for producing descriptions in <EM>termcap</EM> format. + SVr4 <EM>infocmp</EM> does not distinguish between absent and canceled + capabilities. It furthermore reports missing integer capabilities as + <STRONG>-1</STRONG> (its internal representation). <EM>ncurses</EM> shows these as "NULL" for + consistency with missing string capabilities. -</PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 7 (2009) provides a description of <STRONG>infocmp</STRONG>. It - does not mention the options used for converting to termcap format. + The <STRONG>-r</STRONG> option of <EM>ncurses</EM> <EM>infocmp</EM> uses SVr4's notion of "termcap" + capabilities. BSD <EM>curses</EM> had a more restricted set. To see only those + present in 4.4BSD, use "<STRONG>-r</STRONG> <STRONG>-RBSD</STRONG>". </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - Although System V Release 2 provided a terminfo library, it had no + Although System V Release 2 provided a terminfo library, it had no documented tool for decompiling the terminal descriptions. Tony Hansen (AT&T) wrote the first <STRONG>infocmp</STRONG> in early 1984, for System V Release 3. @@ -529,9 +529,7 @@ https://invisible-island.net/ncurses/tctest.html - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -540,9 +538,10 @@ ncurses 6.5 2024-03-16 <STRONG><A HR <li><a href="#h2-DESCRIPTION">DESCRIPTION</a> <ul> <li><a href="#h3-Default-Options">Default Options</a></li> -<li><a href="#h3-Comparison-Options_d_c_n_">Comparison Options [-d] [-c] [-n]</a></li> <li><a href="#h3-Source-Listing-Options_I_L_C_r_">Source Listing Options [-I] [-L] [-C] [-r]</a></li> +<li><a href="#h3-Entry-Comparison-Options_d_c_n_">Entry Comparison Options [-d] [-c] [-n]</a></li> <li><a href="#h3-Use_Option_u_">Use= Option [-u]</a></li> +<li><a href="#h3-Changing-Databases_A-directory_B-directory_">Changing Databases [-A directory] [-B directory]</a></li> <li><a href="#h3-Other-Options">Other Options</a></li> </ul> </li> diff --git a/doc/html/man/infotocap.1m.html b/doc/html/man/infotocap.1m.html index 4213f69428fe..1a0bc1431bb3 100644 --- a/doc/html/man/infotocap.1m.html +++ b/doc/html/man/infotocap.1m.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1999-2010,2016 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: infotocap.1m,v 1.41 2024/03/16 15:35:01 tom Exp @ + * @Id: infotocap.1m,v 1.52 2025/10/04 20:10:32 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>infotocap 1m 2024-03-16 ncurses 6.5 User commands</TITLE> +<TITLE>infotocap 1m 2025-10-04 ncurses 6.6 User commands</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">infotocap 1m 2024-03-16 ncurses 6.5 User commands</H1> +<H1 class="no-header">infotocap 1m 2025-10-04 ncurses 6.6 User commands</H1> <PRE> <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG> User commands <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>infotocap</STRONG> - convert a <EM>terminfo</EM> description into a <EM>termcap</EM> description @@ -58,7 +56,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> <STRONG>infotocap</STRONG> translates terminal descriptions. It looks in each given - text <EM>file</EM> for <EM>terminfo</EM> entries and, For each one found, it writes an + text <EM>file</EM> for <EM>terminfo</EM> entries and, for each one found, writes an analogous <EM>termcap</EM> description to the standard output stream. <EM>terminfo</EM> "<STRONG>use</STRONG>" capabilities translate to <EM>termcap</EM> <STRONG>tc</STRONG> capabilities. Because <EM>termcap</EM> is a less expressive format than <EM>terminfo</EM>, some capabilities @@ -75,9 +73,13 @@ compiled terminal description database +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + This command is an <EM>ncurses</EM> extension. + + </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - None of X/Open Curses, Issue 7 (2009), SVr4, or NetBSD document this - application. + X/Open Curses Issue 7 (2009) does not specify this command. SVr4 and + NetBSD <EM>curses</EM> do not implement it. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> @@ -88,9 +90,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG> +ncurses 6.6 2025-10-04 <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -98,6 +98,7 @@ ncurses 6.5 2024-03-16 <STRONG><A HREF <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-FILES">FILES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-AUTHORS">AUTHORS</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> diff --git a/doc/html/man/key_defined.3x.html b/doc/html/man/key_defined.3x.html index 453decfdb758..fd2b62d79081 100644 --- a/doc/html/man/key_defined.3x.html +++ b/doc/html/man/key_defined.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2003-2006,2010 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,50 +28,52 @@ * authorization. * **************************************************************************** * Author: Thomas E. Dickey 2003 - * @Id: key_defined.3x,v 1.34 2024/03/16 15:35:01 tom Exp @ + * @Id: key_defined.3x,v 1.44 2025/10/04 20:11:22 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>key_defined 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>key_defined 3x 2025-10-04 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">key_defined 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">key_defined 3x 2025-10-04 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> Library calls <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>key_defined</STRONG> - test whether a <EM>curses</EM> keycode is defined + <STRONG>key_defined</STRONG> - obtain key code for an <EM>ncurses</EM> function key definition </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>key_defined(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG><EM>definition</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>key_defined(const</STRONG> <STRONG>char</STRONG> <STRONG>*</STRONG> <EM>definition</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - This is an extension to the <EM>curses</EM> library. It permits an application - to determine if a string is currently bound to any keycode. + The <STRONG>key_defined</STRONG> <EM>ncurses</EM> extension permits a <EM>curses</EM> application to + determine the function key code, if any, to which the string <EM>definition</EM> + is bound. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - If the string is bound to a keycode, its value (greater than zero) is - returned. If no keycode is bound, zero is returned. If the string - conflicts with longer strings which are bound to keys, -1 is returned. + <STRONG>key_defined</STRONG> returns the first key code to which <EM>definition</EM> is bound if + any exists. If none does, it returns <STRONG>0</STRONG>. If <EM>definition</EM> is a prefix of + another bound definition, <STRONG>key_defined</STRONG> returns <STRONG>-1</STRONG>. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>key_defined</STRONG> is an <EM>ncurses</EM> extension. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - This routine is specific to <EM>ncurses</EM>. It was not supported on Version - 7, BSD or System V implementations. It is recommended that any code - depending on them be conditioned using <STRONG>NCURSES_VERSION</STRONG>. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> @@ -79,11 +81,9 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> - - + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG>, <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG> -ncurses 6.5 2024-03-16 <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> +ncurses 6.6 2025-10-04 <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -91,6 +91,7 @@ ncurses 6.5 2024-03-16 <STRONG><A HREF=" <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-AUTHORS">AUTHORS</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> diff --git a/doc/html/man/keybound.3x.html b/doc/html/man/keybound.3x.html index e926e77c6acb..3987e532690a 100644 --- a/doc/html/man/keybound.3x.html +++ b/doc/html/man/keybound.3x.html @@ -28,53 +28,59 @@ * authorization. * **************************************************************************** * Author: Thomas E. Dickey 1999 - * @Id: keybound.3x,v 1.36 2024/03/16 15:35:01 tom Exp @ + * @Id: keybound.3x,v 1.42 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>keybound 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>keybound 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">keybound 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">keybound 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG> Library calls <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>keybound</STRONG> - get definition of <EM>curses</EM> keycode + <STRONG>keybound</STRONG> - get definition of a <EM>curses</EM> function key code </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>keybound(int</STRONG> <EM>keycode</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>count</EM><STRONG>);</STRONG> + <STRONG>char</STRONG> <STRONG>*</STRONG> <STRONG>keybound(int</STRONG> <EM>key-code</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>count</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - This is an extension to the <EM>curses</EM> library. It permits an application - to determine the string which is defined in the terminfo for specific - keycodes. + The <STRONG>keybound</STRONG> <EM>ncurses</EM> extension permits a <EM>curses</EM> application to obtain + the value of the string <EM>bound</EM> to the function key <EM>key-code</EM>; see + <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> (wide-character API users: <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG>). By default, such + bindings are string capabilities from the <EM>terminfo</EM> database entry + corresponding to the terminal type. The application can non- + destructively and repeatedly override such definitions with + <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, as if by pushing new definitions onto a stack. The + <EM>count</EM> parameter accesses the <EM>n</EM>th most recently defined binding; <STRONG>0</STRONG> + selects the binding that is used on input. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The <EM>keycode</EM> parameter must be greater than zero, else <STRONG>NULL</STRONG> is returned. - If it does not correspond to a defined key, then <STRONG>NULL</STRONG> is returned. The - <EM>count</EM> parameter is used to allow the application to iterate through - multiple definitions, counting from zero. When successful, the - function returns a string which must be freed by the caller. + If <EM>key-code</EM> corresponds to a function key defined by the application or + the terminal type in use, <STRONG>keybound</STRONG> allocates and returns a string that + must be freed by the application. <STRONG>keybound</STRONG> returns <EM>NULL</EM> if <EM>key-code</EM> is + not positive or if it does not correspond to a key code definition. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>keybound</STRONG> is an <EM>ncurses</EM> extension. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - This routine is specific to <EM>ncurses</EM>. It was not supported on Version - 7, BSD or System V implementations. It is recommended that any code - depending on them be conditioned using <STRONG>NCURSES_VERSION</STRONG>. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> @@ -82,11 +88,9 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG> - - + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>, <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> -ncurses 6.5 2024-03-16 <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -94,6 +98,7 @@ ncurses 6.5 2024-03-16 <STRONG><A HRE <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-AUTHORS">AUTHORS</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> diff --git a/doc/html/man/keyok.3x.html b/doc/html/man/keyok.3x.html index f94f82f49db1..c03643d6f588 100644 --- a/doc/html/man/keyok.3x.html +++ b/doc/html/man/keyok.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,52 +28,62 @@ * authorization. * **************************************************************************** * Author: Thomas E. Dickey 1997 - * @Id: keyok.3x,v 1.40 2024/03/16 15:35:01 tom Exp @ + * @Id: keyok.3x,v 1.51 2025/10/04 20:59:08 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>keyok 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>keyok 3x 2025-10-04 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">keyok 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">keyok 3x 2025-10-04 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG> Library calls <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>keyok</STRONG> - enable or disable a <EM>curses</EM> keycode + <STRONG>keyok</STRONG> - enable or disable an <EM>ncurses</EM> function key code </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>keyok(int</STRONG> <EM>keycode</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>enable</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>keyok(int</STRONG> <EM>key-code</EM><STRONG>,</STRONG> <STRONG>bool</STRONG> <EM>bf</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - This is an extension to the <EM>curses</EM> library. It permits an application - to disable specific keycodes, rather than use the <STRONG>keypad</STRONG> function to - disable all keycodes. Keys that have been disabled can be re-enabled. + The <STRONG>keyok</STRONG> <EM>ncurses</EM> extension permits a <EM>curses</EM> application to disable a + function key <EM>key-code</EM> returned by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG> (wide-character API users: + <STRONG><A HREF="curs_get_wch.3x.html">wget_wch(3x)</A></STRONG>). Key codes that have been disabled can be re-enabled. + <EM>bf</EM> selects the desired enablement status. This operation is more fine- + grained than calling <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG>, which affects <EM>all</EM> function keys. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The keycode must be greater than zero, else <STRONG>ERR</STRONG> is returned. If it - does not correspond to a defined key, then <STRONG>ERR</STRONG> is returned. If the - <EM>enable</EM> parameter is true, then the key must have been disabled, and - vice versa. Otherwise, the function returns <STRONG>OK</STRONG>. + <STRONG>keyok</STRONG> returns <STRONG>ERR</STRONG> if + + <STRONG>o</STRONG> <EM>key-code</EM> is nonpositive, + + <STRONG>o</STRONG> <EM>key-code</EM> is not a recognized value, or + + <STRONG>o</STRONG> enablement of <EM>key-code</EM> is already in the desired state. + + Otherwise, <STRONG>keyok</STRONG> returns <STRONG>OK</STRONG>. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>keyok</STRONG> is an <EM>ncurses</EM> extension. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - This routine is specific to <EM>ncurses</EM>. It was not supported on Version - 7, BSD or System V implementations. It is recommended that any code - depending on them be conditioned using <STRONG>NCURSES_VERSION</STRONG>. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + + NetBSD <EM>curses</EM> since 2.0 (2004) supports <EM>keyok</EM>. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> @@ -81,11 +91,9 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG> - - + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="define_key.3x.html">define_key(3x)</A></STRONG>, <STRONG><A HREF="keybound.3x.html">keybound(3x)</A></STRONG>, <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG>, <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> -ncurses 6.5 2024-03-16 <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG> +ncurses 6.6 2025-10-04 <STRONG><A HREF="keyok.3x.html">keyok(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -93,6 +101,7 @@ ncurses 6.5 2024-03-16 <STRONG><A <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-AUTHORS">AUTHORS</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> diff --git a/doc/html/man/legacy_coding.3x.html b/doc/html/man/legacy_coding.3x.html index f7b41ba9996b..4591e0fb4336 100644 --- a/doc/html/man/legacy_coding.3x.html +++ b/doc/html/man/legacy_coding.3x.html @@ -28,25 +28,23 @@ * authorization. * **************************************************************************** * Author: Thomas E. Dickey - * @Id: legacy_coding.3x,v 1.28 2024/04/20 19:13:50 tom Exp @ + * @Id: legacy_coding.3x,v 1.32 2024/09/14 20:06:50 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>legacy_coding 3x 2024-04-20 ncurses 6.5 Library calls</TITLE> +<TITLE>legacy_coding 3x 2024-09-14 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">legacy_coding 3x 2024-04-20 ncurses 6.5 Library calls</H1> +<H1 class="no-header">legacy_coding 3x 2024-09-14 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG> Library calls <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>use_legacy_coding</STRONG> - override <EM>curses</EM> locale encoding checks @@ -58,15 +56,15 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - <STRONG>use_legacy_coding</STRONG> is an extension to the <EM>curses</EM> library. It allows the - caller to change the result of <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>, suppressing <STRONG>isprint(3)</STRONG>-based + <STRONG>use_legacy_coding</STRONG>, an <EM>ncurses</EM> extension to the <EM>curses</EM> library, permits + customiztion of <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> behavior, suppressing <STRONG>isprint(3)</STRONG>-based checks within the library that would normally cause nonprinting characters to be rendered in visible form. The alteration affects only - eight-bit characters. + byte-wide characters with the most significant bit set. The <EM>level</EM> parameter controls the result. - <STRONG>0</STRONG> The library functions normally, rendering nonprinting + <STRONG>0</STRONG> The library functions normally, rendering nonprinting characters as described in <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>, <STRONG>1</STRONG> the library ignores <EM>isprint</EM> for codes in the range 160-255. @@ -77,28 +75,33 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - If the screen has not been initialized, or the <EM>level</EM> parameter is out - of range, <STRONG>use_legacy_coding</STRONG> returns <STRONG>ERR</STRONG>. Otherwise, it returns the - previous level: <STRONG>0</STRONG>, <STRONG>1</STRONG>, or <STRONG>2</STRONG>. + If the <EM>curses</EM> screen has not been initialized, or the <EM>level</EM> parameter + is out of range, <STRONG>use_legacy_coding</STRONG> returns <STRONG>ERR</STRONG>. Otherwise, it returns + the previous level. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>use_legacy_coding</STRONG> is an <EM>ncurses</EM> extension. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - <STRONG>use_legacy_coding</STRONG> is specific to <EM>ncurses</EM>. It was not supported on - Version 7, BSD or System V implementations. Applications employing - <EM>ncurses</EM> extensions should condition their use on the visibility of the - <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + <EM>ncurses</EM> 5.6 (2006) introduced <EM>use</EM><STRONG>_</STRONG><EM>legacy</EM><STRONG>_</STRONG><EM>coding</EM> to support <STRONG>lynx(1)</STRONG>'s + font-switching feature. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> - Thomas Dickey (to support <STRONG>lynx(1)</STRONG>'s font-switching feature). + Thomas Dickey </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG> +ncurses 6.6 2024-09-14 <STRONG><A HREF="legacy_coding.3x.html">legacy_coding(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -106,7 +109,9 @@ ncurses 6.5 2024-04-20 <STRONG><A HREF="le <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-AUTHORS">AUTHORS</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> diff --git a/doc/html/man/menu.3x.html b/doc/html/man/menu.3x.html index a499cf1adbd7..c10c5836ba12 100644 --- a/doc/html/man/menu.3x.html +++ b/doc/html/man/menu.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2014,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,27 +28,25 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu.3x,v 1.45 2024/03/16 15:35:01 tom Exp @ + * @Id: menu.3x,v 1.54 2025/11/12 01:27:41 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> Library calls <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - <STRONG>menu</STRONG> - curses extension for programming menus + <STRONG>menu</STRONG> - present menus in <EM>curses</EM> windows </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> @@ -57,9 +55,9 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The <STRONG>menu</STRONG> library provides terminal-independent facilities for composing - menu systems on character-cell terminals. The library includes: item - routines, which create and modify menu items; and menu routines, which - group items into menus, display menus on the screen, and handle + menu systems on character-cell terminals. The library includes: item + routines, which create and modify menu items; and menu routines, which + group items into menus, display menus on the screen, and handle interaction with the user. The <STRONG>menu</STRONG> library uses the <STRONG>curses</STRONG> libraries, and a curses initialization @@ -71,7 +69,7 @@ </PRE><H3><a name="h3-Current-Default-Values-for-Item-Attributes">Current Default Values for Item Attributes</a></H3><PRE> The <STRONG>menu</STRONG> library maintains a default value for item attributes. You can get or set this default by calling the appropriate <STRONG>get_</STRONG> or <STRONG>set_</STRONG> - routine with a <STRONG>NULL</STRONG> item pointer. Changing this default with a <STRONG>set_</STRONG> + routine with a <EM>NULL</EM> item pointer. Changing this default with a <STRONG>set_</STRONG> function affects future item creations, but does not change the rendering of items already created. @@ -112,7 +110,6 @@ menu_pattern <STRONG><A HREF="menu_pattern.3x.html">menu_pattern(3x)</A></STRONG> menu_request_by_name <STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG> menu_request_name <STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG> - menu_spacing <STRONG><A HREF="menu_spacing.3x.html">menu_spacing(3x)</A></STRONG> menu_sub <STRONG><A HREF="menu_win.3x.html">menu_win(3x)</A></STRONG> menu_term <STRONG><A HREF="menu_hook.3x.html">menu_hook(3x)</A></STRONG> @@ -150,7 +147,7 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Routines that return pointers return <STRONG>NULL</STRONG> on error. Routines that + Routines that return pointers return <EM>NULL</EM> on error. Routines that return an integer return one of the following error codes: <STRONG>E_OK</STRONG> The routine succeeded. @@ -218,9 +215,7 @@ <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "menu_" for detailed descriptions of the entry points. - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_attributes.3x.html b/doc/html/man/menu_attributes.3x.html index 3b3f6ea5e2e8..17ddc2c559ca 100644 --- a/doc/html/man/menu_attributes.3x.html +++ b/doc/html/man/menu_attributes.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_attributes 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_attributes 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_attributes 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_attributes 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_attributes.3x.html">menu_attributes(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_attributes.3x.html">menu_attributes(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>menu_back</STRONG>, <STRONG>menu_fore</STRONG>, <STRONG>menu_grey</STRONG>, <STRONG>menu_pad</STRONG>, <STRONG>set_menu_back</STRONG>, <STRONG>set_menu_fore</STRONG>, <STRONG>set_menu_grey</STRONG>, <STRONG>set_menu_pad</STRONG> - color and attribute @@ -79,7 +77,7 @@ default is <STRONG>A_NORMAL</STRONG>. The function <STRONG>set_menu_grey</STRONG> sets the grey attribute of <EM>menu</EM>. This is the - highlight used for un-selectable menu items in menus that permit more + highlight used for un-selectable menu items in menus that permit more than one selection. The function <STRONG>menu_grey</STRONG> returns the grey attribute. The default is <STRONG>A_UNDERLINE</STRONG>. @@ -111,12 +109,10 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "menu_" for detailed + <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> and related pages whose names begin "menu_" for detailed descriptions of the entry points. - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_attributes.3x.html">menu_attributes(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="menu_attributes.3x.html">menu_attributes(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_cursor.3x.html b/doc/html/man/menu_cursor.3x.html index 0003bcdbd4b4..65a7f974d417 100644 --- a/doc/html/man/menu_cursor.3x.html +++ b/doc/html/man/menu_cursor.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_cursor 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_cursor 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_cursor 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_cursor 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_cursor.3x.html">menu_cursor(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_cursor.3x.html">menu_cursor(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>pos_menu_cursor</STRONG> - position a menu's cursor @@ -91,9 +89,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_cursor.3x.html">menu_cursor(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="menu_cursor.3x.html">menu_cursor(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_driver.3x.html b/doc/html/man/menu_driver.3x.html index d82a7f5cedee..669aa1e86c30 100644 --- a/doc/html/man/menu_driver.3x.html +++ b/doc/html/man/menu_driver.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_driver.3x,v 1.47 2024/03/16 15:35:01 tom Exp @ + * @Id: menu_driver.3x,v 1.51 2025/10/04 20:59:08 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_driver 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_driver 3x 2025-10-04 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_driver 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_driver 3x 2025-10-04 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>menu_driver</STRONG> - command-processing loop of the menu system @@ -60,15 +58,15 @@ Once a menu has been posted (displayed), you should funnel input events to it through <STRONG>menu_driver</STRONG>. This routine has three major input cases: - <STRONG>o</STRONG> The input is a form navigation request. Navigation request codes - are constants defined in <STRONG><form.h></STRONG>, which are distinct from the key- + <STRONG>o</STRONG> The input is a menu navigation request. Navigation request codes + are constants defined in <EM>menu.h</EM>, which are distinct from the key- and character codes returned by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>. - <STRONG>o</STRONG> The input is a printable character. Printable characters (which - must be positive, less than 256) are checked according to the + <STRONG>o</STRONG> The input is a printable character. Printable characters (which + must be positive, less than 256) are checked according to the program's locale settings. - <STRONG>o</STRONG> The input is the KEY_MOUSE special key associated with an mouse + <STRONG>o</STRONG> The input is the KEY_MOUSE special key associated with an mouse event. The menu driver requests are as follows: @@ -129,13 +127,13 @@ new pattern. If there is no such match, <STRONG>menu_driver</STRONG> returns <STRONG>E_NO_MATCH</STRONG> and deletes the appended character from the buffer. - If the second argument is one of the above pre-defined requests, the + If the second argument is one of the above pre-defined requests, the corresponding action is performed. </PRE><H3><a name="h3-Mouse-Handling">Mouse Handling</a></H3><PRE> - If the second argument is the KEY_MOUSE special key, the associated - mouse event is translated into one of the above pre-defined requests. + If the second argument is the KEY_MOUSE special key, the associated + mouse event is translated into one of the above pre-defined requests. Currently only clicks in the user window (e.g., inside the menu display area or the decoration window) are handled. @@ -165,16 +163,16 @@ should be returned. It is exactly the purpose of this return value to signal that an application specific command should be executed. - <STRONG>o</STRONG> If a translation into a request was done, <STRONG>menu_driver</STRONG> returns the + <STRONG>o</STRONG> If a translation into a request was done, <STRONG>menu_driver</STRONG> returns the result of this request. - If you clicked outside the user window or the mouse event could not be + If you clicked outside the user window or the mouse event could not be translated into a menu request an <STRONG>E_REQUEST_DENIED</STRONG> is returned. </PRE><H3><a name="h3-Application-defined-Commands">Application-defined Commands</a></H3><PRE> - If the second argument is neither printable nor one of the above pre- - defined menu requests or KEY_MOUSE, the drive assumes it is an + If the second argument is neither printable nor one of the above pre- + defined menu requests or KEY_MOUSE, the drive assumes it is an application-specific command and returns <STRONG>E_UNKNOWN_COMMAND</STRONG>. Application-defined commands should be defined relative to <STRONG>MAX_COMMAND</STRONG>, the maximum value of these pre-defined requests. @@ -221,9 +219,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG> +ncurses 6.6 2025-10-04 <STRONG><A HREF="menu_driver.3x.html">menu_driver(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_format.3x.html b/doc/html/man/menu_format.3x.html index ddd934cfbfbd..8e49fe5d302d 100644 --- a/doc/html/man/menu_format.3x.html +++ b/doc/html/man/menu_format.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_format 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_format 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_format 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_format 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_format.3x.html">menu_format(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_format.3x.html">menu_format(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_menu_format</STRONG>, <STRONG>menu_format</STRONG> - set and get menu sizes @@ -59,17 +57,17 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>set_menu_format</STRONG> sets the maximum display size of the given - menu. If this size is too small to display all menu items, the menu - will be made scrollable. If this size is larger than the menus - subwindow and the subwindow is too small to display all menu items, + menu. If this size is too small to display all menu items, the menu + will be made scrollable. If this size is larger than the menus + subwindow and the subwindow is too small to display all menu items, <STRONG>post_menu</STRONG> will fail. - The default format is 16 rows, 1 column. Calling <STRONG>set_menu_format</STRONG> with - a null menu pointer will change this default. A zero row or column - argument to <STRONG>set_menu_format</STRONG> is interpreted as a request not to change + The default format is 16 rows, 1 column. Calling <STRONG>set_menu_format</STRONG> with + a null menu pointer will change this default. A zero row or column + argument to <STRONG>set_menu_format</STRONG> is interpreted as a request not to change the current value. - The function <STRONG>menu_format</STRONG> returns the maximum-size constraints for the + The function <STRONG>menu_format</STRONG> returns the maximum-size constraints for the given menu into the storage addressed by <STRONG>rows</STRONG> and <STRONG>cols</STRONG>. @@ -92,7 +90,7 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V menu library. They were not + These routines emulate the System V menu library. They were not supported on Version 7 or BSD versions. @@ -104,9 +102,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_format.3x.html">menu_format(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="menu_format.3x.html">menu_format(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_hook.3x.html b/doc/html/man/menu_hook.3x.html index ca1810c27ea9..cd1e5f00466c 100644 --- a/doc/html/man/menu_hook.3x.html +++ b/doc/html/man/menu_hook.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_hook.3x,v 1.32 2024/03/16 15:35:01 tom Exp @ + * @Id: menu_hook.3x,v 1.34 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_hook 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_hook 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_hook 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_hook 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_hook.3x.html">menu_hook(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_hook.3x.html">menu_hook(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>menu_hook</STRONG> - set hooks for automatic invocation by applications @@ -73,27 +71,27 @@ The function <STRONG>set_item_init</STRONG> sets a hook to be called at menu-post time and each time the selected item changes (after the change). <STRONG>item_init</STRONG> - returns the current item init hook, if any (<STRONG>NULL</STRONG> if there is no such + returns the current item init hook, if any (<EM>NULL</EM> if there is no such hook). The function <STRONG>set_item_term</STRONG> sets a hook to be called at menu-unpost time and each time the selected item changes (before the change). <STRONG>item_term</STRONG> - returns the current item term hook, if any (<STRONG>NULL</STRONG> if there is no such + returns the current item term hook, if any (<EM>NULL</EM> if there is no such hook). The function <STRONG>set_menu_init</STRONG> sets a hook to be called at menu-post time and just after the top row on the menu changes once it is posted. - <STRONG>menu_init</STRONG> returns the current menu init hook, if any (<STRONG>NULL</STRONG> if there is + <STRONG>menu_init</STRONG> returns the current menu init hook, if any (<EM>NULL</EM> if there is no such hook). The function <STRONG>set_menu_term</STRONG> sets a hook to be called at menu-unpost time - and just before the top row on the menu changes once it is posted. - <STRONG>menu_term</STRONG> returns the current menu term hook, if any (<STRONG>NULL</STRONG> if there is + and just before the top row on the menu changes once it is posted. + <STRONG>menu_term</STRONG> returns the current menu term hook, if any (<EM>NULL</EM> if there is no such hook). </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Routines that return pointers return <STRONG>NULL</STRONG> on error. Other routines + Routines that return pointers return <EM>NULL</EM> on error. Other routines return one of the following: <STRONG>E_OK</STRONG> The routine succeeded. @@ -103,7 +101,7 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V menu library. They were not + These routines emulate the System V menu library. They were not supported on Version 7 or BSD versions. @@ -115,9 +113,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_hook.3x.html">menu_hook(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="menu_hook.3x.html">menu_hook(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_items.3x.html b/doc/html/man/menu_items.3x.html index 7f1c08249cce..943ac12e2d7a 100644 --- a/doc/html/man/menu_items.3x.html +++ b/doc/html/man/menu_items.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_items.3x,v 1.34 2024/03/16 15:35:01 tom Exp @ + * @Id: menu_items.3x,v 1.36 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_items 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_items 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_items 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_items 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_items.3x.html">menu_items(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_items.3x.html">menu_items(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_menu_items</STRONG>, <STRONG>menu_items</STRONG>, <STRONG>item_count</STRONG> - make and break connections between items and menus @@ -61,7 +59,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>set_menu_items</STRONG> changes the item pointer array of the given - <EM>menu</EM>. The array must be terminated by a <STRONG>NULL</STRONG>. + <EM>menu</EM>. The array must be terminated by a <EM>NULL</EM>. The function <STRONG>menu_items</STRONG> returns the item array of the given menu. @@ -69,11 +67,11 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The function <STRONG>menu_items</STRONG> returns a pointer (which may be <STRONG>NULL</STRONG>). It does + The function <STRONG>menu_items</STRONG> returns a pointer (which may be <EM>NULL</EM>). It does not set <STRONG>errno</STRONG>. The function <STRONG>item_count</STRONG> returns <STRONG>ERR</STRONG> (the general <STRONG>curses</STRONG> error return - value) if its <EM>menu</EM> parameter is <STRONG>NULL</STRONG>. + value) if its <EM>menu</EM> parameter is <EM>NULL</EM> <EM>.</EM> The function <STRONG>set_menu_items</STRONG> returns one of the following codes on error: @@ -109,9 +107,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_items.3x.html">menu_items(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="menu_items.3x.html">menu_items(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_mark.3x.html b/doc/html/man/menu_mark.3x.html index 1cdb2b051b10..ea695e25ccfd 100644 --- a/doc/html/man/menu_mark.3x.html +++ b/doc/html/man/menu_mark.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_mark.3x,v 1.35 2024/03/16 15:35:01 tom Exp @ + * @Id: menu_mark.3x,v 1.37 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_mark 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_mark 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_mark 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_mark 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_mark.3x.html">menu_mark(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_mark.3x.html">menu_mark(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_menu_mark</STRONG>, <STRONG>menu_mark</STRONG> - get and set the menu mark string @@ -62,20 +60,20 @@ highlighting or color capability, the menu library marks selected items in a menu with a prefix string. - The function <STRONG>set_menu_mark</STRONG> sets the mark string for the given menu. - Calling <STRONG>set_menu_mark</STRONG> with a null menu item will abolish the mark - string. Note that changing the length of the mark string for a menu + The function <STRONG>set_menu_mark</STRONG> sets the mark string for the given menu. + Calling <STRONG>set_menu_mark</STRONG> with a null menu item will abolish the mark + string. Note that changing the length of the mark string for a menu while the menu is posted is likely to produce unhelpful behavior. - The default string is "-" (a dash). Calling <STRONG>set_menu_mark</STRONG> with a non- - <STRONG>NULL</STRONG> menu argument will change this default. + The default string is "-" (a dash). Calling <STRONG>set_menu_mark</STRONG> with a <EM>non-</EM> + NULL menu argument will change this default. - The function <STRONG>menu_mark</STRONG> returns the menu's mark string (or <STRONG>NULL</STRONG> if there + The function <STRONG>menu_mark</STRONG> returns the menu's mark string (or <EM>NULL</EM> if there is none). </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The function <STRONG>menu_mark</STRONG> returns a pointer (which may be <STRONG>NULL</STRONG>). It does + The function <STRONG>menu_mark</STRONG> returns a pointer (which may be <EM>NULL</EM>). It does not set <STRONG>errno</STRONG>. The function <STRONG>set_menu_mark</STRONG> may return the following error codes: @@ -102,9 +100,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_mark.3x.html">menu_mark(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="menu_mark.3x.html">menu_mark(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_new.3x.html b/doc/html/man/menu_new.3x.html index e53eacb65c44..87178bfe186a 100644 --- a/doc/html/man/menu_new.3x.html +++ b/doc/html/man/menu_new.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_new.3x,v 1.35 2024/03/16 15:35:01 tom Exp @ + * @Id: menu_new.3x,v 1.37 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_new 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_new 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_new 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_new 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_new.3x.html">menu_new(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_new.3x.html">menu_new(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>new_menu</STRONG>, <STRONG>free_menu</STRONG> - create and destroy menus @@ -59,14 +57,14 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>new_menu</STRONG> creates a new menu connected to a specified item - pointer array (which must be <STRONG>NULL</STRONG>-terminated). + pointer array (which must be <EM>NULL</EM>-terminated). The function <STRONG>free_menu</STRONG> disconnects <EM>menu</EM> from its item array and frees the storage allocated for the menu. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The function <STRONG>new_menu</STRONG> returns <STRONG>NULL</STRONG> on error. It sets <STRONG>errno</STRONG> according + The function <STRONG>new_menu</STRONG> returns <EM>NULL</EM> on error. It sets <STRONG>errno</STRONG> according to the function's failure: <STRONG>E_NOT_CONNECTED</STRONG> @@ -102,9 +100,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_new.3x.html">menu_new(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="menu_new.3x.html">menu_new(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_opts.3x.html b/doc/html/man/menu_opts.3x.html index 453526ab206b..b0d94851ac75 100644 --- a/doc/html/man/menu_opts.3x.html +++ b/doc/html/man/menu_opts.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2015,2016 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_opts.3x,v 1.35 2024/03/16 15:35:01 tom Exp @ + * @Id: menu_opts.3x,v 1.38 2025/01/19 00:51:10 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_opts 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_opts 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_opts 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_opts 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_opts.3x.html">menu_opts(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_opts.3x.html">menu_opts(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_menu_opts</STRONG>, <STRONG>menu_opts_on</STRONG>, <STRONG>menu_opts_off</STRONG>, <STRONG>menu_opts</STRONG> - set and get menu options @@ -63,7 +61,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>set_menu_opts</STRONG> sets all the given menu's option bits (menu - option bits may be logically-OR'ed together). + option bits may be logically "or"-ed together). The function <STRONG>menu_opts_on</STRONG> turns on the given option bits, and leaves others alone. @@ -126,9 +124,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_opts.3x.html">menu_opts(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="menu_opts.3x.html">menu_opts(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_pattern.3x.html b/doc/html/man/menu_pattern.3x.html index 34d6f98d2cb8..cc6fa5ed8b80 100644 --- a/doc/html/man/menu_pattern.3x.html +++ b/doc/html/man/menu_pattern.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_pattern.3x,v 1.38 2024/03/16 15:35:01 tom Exp @ + * @Id: menu_pattern.3x,v 1.40 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_pattern 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_pattern 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_pattern 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_pattern 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_pattern.3x.html">menu_pattern(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_pattern.3x.html">menu_pattern(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_menu_pattern</STRONG>, <STRONG>menu_pattern</STRONG> - set and get a menu's pattern buffer @@ -70,8 +68,8 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The function <STRONG>menu_pattern</STRONG> returns a pointer, which is <STRONG>NULL</STRONG> if the <EM>menu</EM> - parameter is <STRONG>NULL</STRONG>. Otherwise, it is a pointer to a string which is + The function <STRONG>menu_pattern</STRONG> returns a pointer, which is <EM>NULL</EM> if the <EM>menu</EM> + parameter is <EM>NULL</EM>. Otherwise, it is a pointer to a string which is empty if no pattern has been set. It does not set <STRONG>errno</STRONG>. The function <STRONG>set_menu_pattern</STRONG> may return the following error codes: @@ -107,9 +105,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_pattern.3x.html">menu_pattern(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="menu_pattern.3x.html">menu_pattern(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_post.3x.html b/doc/html/man/menu_post.3x.html index 6d48f77b05a7..6e67aabe23b7 100644 --- a/doc/html/man/menu_post.3x.html +++ b/doc/html/man/menu_post.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_post 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_post 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_post 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_post 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_post.3x.html">menu_post(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_post.3x.html">menu_post(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>post_menu</STRONG>, <STRONG>unpost_menu</STRONG> - write or erase menus from associated subwindows @@ -60,7 +58,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>post_menu</STRONG> displays a menu to its associated subwindow. To - trigger physical display of the subwindow, use <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> or some + trigger physical display of the subwindow, use <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> or some equivalent <STRONG>curses</STRONG> routine (the implicit <STRONG>doupdate</STRONG> triggered by an <STRONG>curses</STRONG> input request will do). <STRONG>post_menu</STRONG> resets the selection status of all items. @@ -109,9 +107,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_post.3x.html">menu_post(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="menu_post.3x.html">menu_post(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_requestname.3x.html b/doc/html/man/menu_requestname.3x.html index 0a06ada495bd..afcd06bce3c2 100644 --- a/doc/html/man/menu_requestname.3x.html +++ b/doc/html/man/menu_requestname.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_requestname.3x,v 1.33 2024/03/16 15:35:01 tom Exp @ + * @Id: menu_requestname.3x,v 1.35 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_requestname 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_requestname 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_requestname 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_requestname 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>menu_request_by_name</STRONG>, <STRONG>menu_request_name</STRONG> - handle printable menu request names @@ -59,22 +57,22 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The function <STRONG>menu_request_name</STRONG> returns the printable name of a menu + The function <STRONG>menu_request_name</STRONG> returns the printable name of a menu request code. - The function <STRONG>menu_request_by_name</STRONG> searches in the name-table for a - request with the given name and returns its request code. Otherwise + The function <STRONG>menu_request_by_name</STRONG> searches in the name-table for a + request with the given name and returns its request code. Otherwise E_NO_MATCH is returned. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - <STRONG>menu_request_name</STRONG> returns <STRONG>NULL</STRONG> on error and sets <STRONG>errno</STRONG> to + <STRONG>menu_request_name</STRONG> returns <EM>NULL</EM> on error and sets <STRONG>errno</STRONG> to <STRONG>E_BAD_ARGUMENT</STRONG>. - <STRONG>menu_request_by_name</STRONG> returns <STRONG>E_NO_MATCH</STRONG> on error. It does not set + <STRONG>menu_request_by_name</STRONG> returns <STRONG>E_NO_MATCH</STRONG> on error. It does not set <STRONG>errno</STRONG>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines are specific to <EM>ncurses</EM>. They were not supported on + These routines are specific to <EM>ncurses</EM>. They were not supported on Version 7, BSD or System V implementations. It is recommended that any code depending on them be conditioned using NCURSES_VERSION. @@ -87,9 +85,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="menu_requestname.3x.html">menu_requestname(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_spacing.3x.html b/doc/html/man/menu_spacing.3x.html index 5526b4dea54f..8c9a834c5f66 100644 --- a/doc/html/man/menu_spacing.3x.html +++ b/doc/html/man/menu_spacing.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_spacing.3x,v 1.37 2024/03/16 15:35:01 tom Exp @ + * @Id: menu_spacing.3x,v 1.39 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_spacing 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_spacing 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_spacing 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_spacing 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_spacing.3x.html">menu_spacing(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_spacing.3x.html">menu_spacing(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_menu_spacing</STRONG>, <STRONG>menu_spacing</STRONG> - set and get spacing between menu items. @@ -70,24 +68,24 @@ columns). <EM>spc</EM><STRONG>_</STRONG><EM>description</EM> - controls the number of spaces between an item name and an item - description. It must not be larger than <STRONG>TABSIZE</STRONG>. The menu + controls the number of spaces between an item name and an item + description. It must not be larger than <STRONG>TABSIZE</STRONG>. The menu system puts in the middle of this spacing area the pad character. The remaining parts are filled with spaces. <EM>spc</EM><STRONG>_</STRONG><EM>rows</EM> - controls the number of rows that are used for an item. It must - not be larger than 3. The menu system inserts the blank lines + controls the number of rows that are used for an item. It must + not be larger than 3. The menu system inserts the blank lines between item rows, these lines will contain the pad character in the appropriate positions. <EM>spc</EM><STRONG>_</STRONG><EM>columns</EM> controls the number of blanks between columns of items. It must - not be larger than <STRONG>TABSIZE</STRONG>. A value of 0 for all the spacing + not be larger than <STRONG>TABSIZE</STRONG>. A value of 0 for all the spacing values resets them to the default, which is 1 for all of them. The function <STRONG>menu_spacing</STRONG> returns the spacing information for the menu. - If a pointer is NULL, the corresponding information is simply not + If a pointer is <EM>NULL</EM>, the corresponding information is simply not returned. @@ -98,7 +96,7 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines are specific to <EM>ncurses</EM>. They were not supported on + These routines are specific to <EM>ncurses</EM>. They were not supported on Version 7, BSD or System V implementations. It is recommended that any code depending on them be conditioned using NCURSES_VERSION. @@ -111,9 +109,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_spacing.3x.html">menu_spacing(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="menu_spacing.3x.html">menu_spacing(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_userptr.3x.html b/doc/html/man/menu_userptr.3x.html index d2b52f1df4ed..65e4b74291bf 100644 --- a/doc/html/man/menu_userptr.3x.html +++ b/doc/html/man/menu_userptr.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_userptr.3x,v 1.33 2024/03/16 15:35:01 tom Exp @ + * @Id: menu_userptr.3x,v 1.35 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_userptr 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_userptr 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_userptr 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_userptr 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_userptr.3x.html">menu_userptr(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_userptr.3x.html">menu_userptr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_menu_userptr</STRONG>, <STRONG>menu_userptr</STRONG> - associate application data with a menu item @@ -59,20 +57,20 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - Every menu and every menu item has a field that can be used to hold - application-specific data (that is, the menu-driver code leaves it + Every menu and every menu item has a field that can be used to hold + application-specific data (that is, the menu-driver code leaves it alone). These functions get and set the menu user pointer field. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - <STRONG>menu_userptr</STRONG> returns a pointer (which may be <STRONG>NULL</STRONG>). It does not set + <STRONG>menu_userptr</STRONG> returns a pointer (which may be <EM>NULL</EM>). It does not set <STRONG>errno</STRONG>. <STRONG>set_menu_userptr</STRONG> returns <STRONG>E_OK</STRONG> (success). </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V menu library. They were not + These routines emulate the System V menu library. They were not supported on Version 7 or BSD versions. The user pointer is a void pointer. We chose not to leave it as a char @@ -87,9 +85,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_userptr.3x.html">menu_userptr(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="menu_userptr.3x.html">menu_userptr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/menu_win.3x.html b/doc/html/man/menu_win.3x.html index 9688e0f506ce..27d288530908 100644 --- a/doc/html/man/menu_win.3x.html +++ b/doc/html/man/menu_win.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: menu_win.3x,v 1.32 2024/03/16 15:35:01 tom Exp @ + * @Id: menu_win.3x,v 1.34 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>menu_win 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>menu_win 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">menu_win 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">menu_win 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="menu_win.3x.html">menu_win(3x)</A></STRONG> Library calls <STRONG><A HREF="menu_win.3x.html">menu_win(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>menu_win</STRONG> - make and break menu window and subwindow associations @@ -72,8 +70,8 @@ necessary to set either window; by default, the driver code uses <STRONG>stdscr</STRONG> for both. - In the <STRONG>set_</STRONG> functions, window argument of <STRONG>NULL</STRONG> is treated as though it - were <STRONG>stsdcr</STRONG>. A menu argument of <STRONG>NULL</STRONG> is treated as a request to change + In the <STRONG>set_</STRONG> functions, window argument of <EM>NULL</EM> is treated as though it + were <STRONG>stsdcr</STRONG>. A menu argument of <EM>NULL</EM> is treated as a request to change the system default menu window or subwindow. The function <STRONG>scale_menu</STRONG> returns the minimum size required for the @@ -81,7 +79,7 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Routines that return pointers return <STRONG>NULL</STRONG> on error. Routines that + Routines that return pointers return <EM>NULL</EM> on error. Routines that return an integer return one of the following error codes: <STRONG>E_OK</STRONG> The routine succeeded. @@ -112,9 +110,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="menu_win.3x.html">menu_win(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="menu_win.3x.html">menu_win(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/mitem_current.3x.html b/doc/html/man/mitem_current.3x.html index ea8a33f7ddc9..161e9896db30 100644 --- a/doc/html/man/mitem_current.3x.html +++ b/doc/html/man/mitem_current.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: mitem_current.3x,v 1.37 2024/03/16 15:35:01 tom Exp @ + * @Id: mitem_current.3x,v 1.39 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>mitem_current 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>mitem_current 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">mitem_current 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">mitem_current 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="mitem_current.3x.html">mitem_current(3x)</A></STRONG> Library calls <STRONG><A HREF="mitem_current.3x.html">mitem_current(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>mitem_current</STRONG> - set and get current_menu_item @@ -68,21 +66,21 @@ current item in the given menu. The function <STRONG>set_top_row</STRONG> sets the top row of the menu to show the given - row (the top row is initially 0, and is reset to this value whenever - the <STRONG>O_ROWMAJOR</STRONG> option is toggled). The item leftmost on the given row - becomes current. The function <STRONG>top_row</STRONG> returns the number of the top + row (the top row is initially 0, and is reset to this value whenever + the <STRONG>O_ROWMAJOR</STRONG> option is toggled). The item leftmost on the given row + becomes current. The function <STRONG>top_row</STRONG> returns the number of the top menu row being displayed. - The function <STRONG>item_index</STRONG> returns the (zero-origin) index of <EM>item</EM> in the + The function <STRONG>item_index</STRONG> returns the (zero-origin) index of <EM>item</EM> in the menu's item pointer list. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - <STRONG>current_item</STRONG> returns a pointer (which may be <STRONG>NULL</STRONG>). It does not set + <STRONG>current_item</STRONG> returns a pointer (which may be <EM>NULL</EM>). It does not set <STRONG>errno</STRONG>. - <STRONG>top_row</STRONG> and <STRONG>item_index</STRONG> return <STRONG>ERR</STRONG> (the general <STRONG>curses</STRONG> error value) if - their <EM>menu</EM> parameter is <STRONG>NULL</STRONG>. + <STRONG>top_row</STRONG> and <STRONG>item_index</STRONG> return <STRONG>ERR</STRONG> (the general <STRONG>curses</STRONG> error value) if + their <EM>menu</EM> parameter is <EM>NULL</EM>. <STRONG>set_current_item</STRONG> and <STRONG>set_top_row</STRONG> return one of the following: @@ -102,10 +100,10 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V menu library. They were not + These routines emulate the System V menu library. They were not supported on Version 7 or BSD versions. - The SVr4 menu library documentation specifies the <STRONG>top_row</STRONG> and + The SVr4 menu library documentation specifies the <STRONG>top_row</STRONG> and <STRONG>index_item</STRONG> error value as -1 (which is the value of <STRONG>ERR</STRONG>). @@ -117,9 +115,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="mitem_current.3x.html">mitem_current(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="mitem_current.3x.html">mitem_current(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/mitem_name.3x.html b/doc/html/man/mitem_name.3x.html index 1ff53c8a9437..e96ac6fd8021 100644 --- a/doc/html/man/mitem_name.3x.html +++ b/doc/html/man/mitem_name.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: mitem_name.3x,v 1.31 2024/03/16 15:35:01 tom Exp @ + * @Id: mitem_name.3x,v 1.33 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>mitem_name 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>mitem_name 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">mitem_name 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">mitem_name 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="mitem_name.3x.html">mitem_name(3x)</A></STRONG> Library calls <STRONG><A HREF="mitem_name.3x.html">mitem_name(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>item_name</STRONG>, <STRONG>item_description</STRONG> - get menu item name and description fields @@ -64,12 +62,12 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - These routines return a pointer (which may be <STRONG>NULL</STRONG>). They do not set + These routines return a pointer (which may be <EM>NULL</EM>). They do not set <STRONG>errno</STRONG>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V menu library. They were not + These routines emulate the System V menu library. They were not supported on Version 7 or BSD versions. @@ -81,9 +79,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="mitem_name.3x.html">mitem_name(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="mitem_name.3x.html">mitem_name(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/mitem_new.3x.html b/doc/html/man/mitem_new.3x.html index b4ed66765bb7..bb1f258c682c 100644 --- a/doc/html/man/mitem_new.3x.html +++ b/doc/html/man/mitem_new.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: mitem_new.3x,v 1.36 2024/03/16 15:35:01 tom Exp @ + * @Id: mitem_new.3x,v 1.38 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>mitem_new 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>mitem_new 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">mitem_new 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">mitem_new 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="mitem_new.3x.html">mitem_new(3x)</A></STRONG> Library calls <STRONG><A HREF="mitem_new.3x.html">mitem_new(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>new_item</STRONG>, <STRONG>free_item</STRONG> - create and destroy menu items @@ -69,7 +67,7 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The function <STRONG>new_item</STRONG> returns <STRONG>NULL</STRONG> on error. It sets <STRONG>errno</STRONG> according + The function <STRONG>new_item</STRONG> returns <EM>NULL</EM> on error. It sets <STRONG>errno</STRONG> according to the function's failure: <STRONG>E_BAD_ARGUMENT</STRONG> @@ -105,9 +103,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="mitem_new.3x.html">mitem_new(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="mitem_new.3x.html">mitem_new(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/mitem_opts.3x.html b/doc/html/man/mitem_opts.3x.html index 537a91301e0f..6375a7853606 100644 --- a/doc/html/man/mitem_opts.3x.html +++ b/doc/html/man/mitem_opts.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2015 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: mitem_opts.3x,v 1.33 2024/03/16 15:35:01 tom Exp @ + * @Id: mitem_opts.3x,v 1.36 2025/01/19 00:51:10 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>mitem_opts 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>mitem_opts 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">mitem_opts 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">mitem_opts 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="mitem_opts.3x.html">mitem_opts(3x)</A></STRONG> Library calls <STRONG><A HREF="mitem_opts.3x.html">mitem_opts(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_item_opts</STRONG>, <STRONG>item_opts_on</STRONG>, <STRONG>item_opts_off</STRONG>, <STRONG>item_opts</STRONG> - set and get menu item options @@ -63,7 +61,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The function <STRONG>set_item_opts</STRONG> sets all the given item's option bits (menu - option bits may be logically-OR'ed together). + option bits may be logically "or"-ed together). The function <STRONG>item_opts_on</STRONG> turns on the given option bits, and leaves others alone. @@ -100,9 +98,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="mitem_opts.3x.html">mitem_opts(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="mitem_opts.3x.html">mitem_opts(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/mitem_userptr.3x.html b/doc/html/man/mitem_userptr.3x.html index afb442d81c63..6178989f8cd6 100644 --- a/doc/html/man/mitem_userptr.3x.html +++ b/doc/html/man/mitem_userptr.3x.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: mitem_userptr.3x,v 1.34 2024/03/16 15:35:01 tom Exp @ + * @Id: mitem_userptr.3x,v 1.36 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>mitem_userptr 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>mitem_userptr 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">mitem_userptr 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">mitem_userptr 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="mitem_userptr.3x.html">mitem_userptr(3x)</A></STRONG> Library calls <STRONG><A HREF="mitem_userptr.3x.html">mitem_userptr(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_item_userptr</STRONG>, <STRONG>item_userptr</STRONG> - associate application data with a menu item @@ -59,20 +57,20 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - Every menu item has a field that can be used to hold application- - specific data (that is, the menu-driver code leaves it alone). These + Every menu item has a field that can be used to hold application- + specific data (that is, the menu-driver code leaves it alone). These functions get and set that field. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - The function <STRONG>item_userptr</STRONG> returns a pointer (possibly <STRONG>NULL</STRONG>). It does + The function <STRONG>item_userptr</STRONG> returns a pointer (possibly <EM>NULL</EM>). It does not set <STRONG>errno</STRONG>. The <STRONG>set_item_userptr</STRONG> always returns <STRONG>E_OK</STRONG> (success). </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - These routines emulate the System V menu library. They were not + These routines emulate the System V menu library. They were not supported on Version 7 or BSD versions. The user pointer is a void pointer. We chose not to leave it as a char @@ -87,9 +85,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="mitem_userptr.3x.html">mitem_userptr(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="mitem_userptr.3x.html">mitem_userptr(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/mitem_value.3x.html b/doc/html/man/mitem_value.3x.html index 01ce5d506a21..f9ed1b01b16b 100644 --- a/doc/html/man/mitem_value.3x.html +++ b/doc/html/man/mitem_value.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>mitem_value 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>mitem_value 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">mitem_value 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">mitem_value 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="mitem_value.3x.html">mitem_value(3x)</A></STRONG> Library calls <STRONG><A HREF="mitem_value.3x.html">mitem_value(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>set_item_value</STRONG>, <STRONG>item_value</STRONG> - set and get menu item values @@ -59,7 +57,7 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> If you turn off the menu option <STRONG>O_ONEVALUE</STRONG> (e.g., with <STRONG>set_menu_opts</STRONG> or - <STRONG>menu_opts_off</STRONG>; see <STRONG><A HREF="menu_opts.3x.html">menu_opts(3x)</A></STRONG>), the menu becomes multi-valued; that + <STRONG>menu_opts_off</STRONG>; see <STRONG><A HREF="menu_opts.3x.html">menu_opts(3x)</A></STRONG>), the menu becomes multi-valued; that is, more than one item may simultaneously be selected. In a multi_valued menu, you can used <STRONG>set_item_value</STRONG> to select the given @@ -92,9 +90,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="mitem_value.3x.html">mitem_value(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="mitem_value.3x.html">mitem_value(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/mitem_visible.3x.html b/doc/html/man/mitem_visible.3x.html index 8224323f3282..be2159d7c190 100644 --- a/doc/html/man/mitem_visible.3x.html +++ b/doc/html/man/mitem_visible.3x.html @@ -34,18 +34,16 @@ <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>mitem_visible 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>mitem_visible 3x 2024-03-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">mitem_visible 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">mitem_visible 3x 2024-03-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="mitem_visible.3x.html">mitem_visible(3x)</A></STRONG> Library calls <STRONG><A HREF="mitem_visible.3x.html">mitem_visible(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>item_visible</STRONG> - check visibility of a menu item @@ -75,9 +73,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="mitem_visible.3x.html">mitem_visible(3x)</A></STRONG> +ncurses 6.6 2024-03-16 <STRONG><A HREF="mitem_visible.3x.html">mitem_visible(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/ncurses.3x.html b/doc/html/man/ncurses.3x.html index 9b061acba0e0..b27c8380d579 100644 --- a/doc/html/man/ncurses.3x.html +++ b/doc/html/man/ncurses.3x.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: ncurses.3x,v 1.214 2024/04/27 17:55:43 tom Exp @ + * @Id: ncurses.3x,v 1.289 2025/11/12 01:01:34 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>ncurses 3x 2024-04-27 ncurses 6.5 Library calls</TITLE> +<TITLE>ncurses 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">ncurses 3x 2024-04-27 ncurses 6.5 Library calls</H1> +<H1 class="no-header">ncurses 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> Library calls <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>ncurses</STRONG> - character-cell terminal interface with optimized output @@ -57,24 +55,23 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> The "new curses" library offers the programmer a terminal-independent - means of reading keyboard and mouse input and updating character-cell - terminals with output optimized to minimize screen updates. <EM>ncurses</EM> + means of reading keyboard and mouse input and writing to character-cell + displays with output optimized to minimize screen updates. <EM>ncurses</EM> replaces the <EM>curses</EM> libraries from System V Release 4 Unix ("SVr4") and 4.4BSD Unix, the development of which ceased in the 1990s. This - document describes <EM>ncurses</EM> version 6.5 (patch 20240427). + document describes <EM>ncurses</EM> version 6.6 (patch 20251230). <EM>ncurses</EM> permits control of the terminal screen's contents; abstraction - and subdivision thereof with <EM>windows</EM> and <EM>pads</EM>; the reading of terminal - input; control of terminal input and output options; environment query - routines; color manipulation; the definition and use of <EM>soft</EM> <EM>label</EM> - keys; <EM>terminfo</EM> capability access; a <EM>termcap</EM> compatibility interface; - and an abstraction of the system's API for manipulating the terminal - (such as <STRONG>termios(3)</STRONG>). - - <EM>ncurses</EM> implements the standard interface described by X/Open Curses - Issue 7. In many behavioral details not standardized by X/Open, - <EM>ncurses</EM> emulates the <EM>curses</EM> library of SVr4 and provides numerous - useful extensions. + and subdivision thereof with <EM>windows</EM> and <EM>pads</EM>; acquisition of keyboard + and mouse events; selection of color and rendering attributes (such as + bold or underline); the definition and use of <EM>soft</EM> <EM>label</EM> keys; access + to the <EM>terminfo</EM> terminal capability database; a <EM>termcap</EM> compatibility + interface; and an abstraction of the system's API for manipulating the + terminal (such as <STRONG>termios(3)</STRONG>). + + <EM>ncurses</EM> implements the interface described by X/Open Curses Issue 7. + In many behavioral details not standardized by X/Open, <EM>ncurses</EM> emulates + the <EM>curses</EM> library of SVr4 and provides numerous useful extensions. <EM>ncurses</EM> man pages employ several sections to clarify matters of usage and interoperability with other <EM>curses</EM> implementations. @@ -84,8 +81,8 @@ underlying integral type or the availability of a preprocessor macro exclusive of a function definition (which prevents its address from being taken). This section also describes - implementation details that will be significant to the programmer - but which are not standardized. + implementation details of significance to the programmer but which + are not standardized. <STRONG>o</STRONG> "EXTENSIONS" presents <EM>ncurses</EM> innovations beyond the X/Open Curses standard and/or the SVr4 <EM>curses</EM> implementation. They are termed @@ -97,7 +94,7 @@ that should be considered when writing to a <EM>curses</EM> standard, or for multiple implementations. - <STRONG>o</STRONG> "HISTORY" examines points of detail in <EM>ncurses</EM> and other <EM>curses</EM> + <STRONG>o</STRONG> "HISTORY" examines points of detail in <EM>ncurses</EM> and other <EM>curses</EM> implementations over the decades of their development, particularly where precedent or inertia have frustrated better design (and, in a few cases, where such inertia has been overcome). @@ -106,94 +103,100 @@ option to your compiler or linker. A debugging version of the library may be available; if so, link with it using <STRONG>-lncurses_g</STRONG>. (Your system integrator may have installed these libraries such that you can use the - options <STRONG>-lcurses</STRONG> and <STRONG>-lcurses_g</STRONG>, respectively.) The <EM>ncurses</EM><STRONG>_</STRONG><EM>g</EM> library - generates trace logs (in a file called <EM>trace</EM> in the current directory) - that describe <EM>ncurses</EM> actions. See section "ALTERNATE CONFIGURATIONS" - below. + options <STRONG>-lcurses</STRONG> and <STRONG>-lcurses_g</STRONG>, respectively.) The <EM>ncurses</EM><STRONG>_</STRONG><EM>g</EM> library + logs events describing <EM>ncurses</EM> actions to a file called <EM>trace</EM> in the + application's working directory at startup. See section "ALTERNATE + CONFIGURATIONS" below. </PRE><H3><a name="h3-Application-Structure">Application Structure</a></H3><PRE> - A <EM>curses</EM> application uses information from the system locale; + A <EM>curses</EM> application uses information from the system locale; <STRONG>setlocale(3)</STRONG> prepares it for <EM>curses</EM> library calls. setlocale(LC_ALL, ""); - If the locale is not thus initialized, the library assumes that - characters are printable as in ISO 8859-1, to work with certain legacy - programs. You should initialize the locale; do not expect consistent + If the locale is not thus initialized, the library assumes that + characters are printable as in ISO 8859-1, to work with certain legacy + programs. You should initialize the locale; do not expect consistent behavior from the library when the locale has not been set up. - <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> must be called to initialize <EM>curses</EM> before - use of any functions that deal with windows and screens. + <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> must be called to initialize <EM>curses</EM> before + use of any functions that access or manipulate windows or screens. - To get character-at-a-time input without echoing--most interactive, - screen-oriented programs want this--use the following sequence. + To get character-at-a-time input without echoing -- most interactive, + screen-oriented programs want this -- use the following sequence. initscr(); cbreak(); noecho(); - Most applications perform further setup as follows. + Most applications would perform further setup as follows. - intrflush(stdscr, FALSE); + noqiflush(); keypad(stdscr, TRUE); - A <EM>curses</EM> program then often enters an event loop of some sort. Call + A <EM>curses</EM> program then often enters an event-handling loop. Call <STRONG><A HREF="curs_initscr.3x.html">endwin(3x)</A></STRONG> before exiting. </PRE><H3><a name="h3-Overview">Overview</a></H3><PRE> - A <EM>curses</EM> library abstracts the terminal screen by representing all or - part of it as a <EM>WINDOW</EM> data structure. A <EM>window</EM> is a rectangular grid - of character cells, addressed by row and column coordinates (<EM>y</EM>, <EM>x</EM>), - with the upper left corner as (0, 0). A window called <STRONG>stdscr</STRONG>, the same - size as the terminal screen, is always available. Create others with - <STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>. - - A <EM>curses</EM> library does not manage overlapping windows (but see below). - You can either use <STRONG>stdscr</STRONG> to manage one screen-filling window, or tile - the screen into non-overlapping windows and not use <STRONG>stdscr</STRONG> at all. - Mixing the two approaches will result in unpredictable and undesired + A <EM>curses</EM> library abstracts the terminal with a <EM>SCREEN</EM> data structure, + and represents all or part of its display with <EM>WINDOW</EM> structures. + Distinct properties apply to each; for example, the <EM>line</EM> <EM>discipline</EM> of + a typical Unix terminal driver is in one of three modes: raw, cbreak, + or canonical ("cooked"). In <EM>curses</EM>, the line discipline is a property + of the screen, applying identically to all windows associated with it. + + A <EM>window</EM> is a rectangular grid of character cells, addressed by line + and column coordinates (<EM>y</EM>, <EM>x</EM>), with the upper left corner as (0, 0). A + window called <STRONG>stdscr</STRONG>, by default the same size as the terminal screen, + is always available. Create others with <STRONG><A HREF="curs_window.3x.html">newwin(3x)</A></STRONG>. + + A <EM>curses</EM> library does not manage overlapping windows (but see below). + You can either use <STRONG>stdscr</STRONG> to manage one screen-filling window, or tile + the screen into non-overlapping windows and not use <STRONG>stdscr</STRONG> at all. + Mixing the two approaches will result in unpredictable and undesired effects. - Functions permit manipulation of a window and the <EM>cursor</EM> identifying - the cell within it at which the next output operation will occur. - Among those, the most basic are <STRONG><A HREF="curs_move.3x.html">move(3x)</A></STRONG> and <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>: these place the - cursor and write a character to <STRONG>stdscr</STRONG>, respectively. + Functions permit manipulation of a window and the <EM>cursor</EM> identifying + the cell within it at which the next operation will occur. Among + those, the most basic are <STRONG><A HREF="curs_move.3x.html">move(3x)</A></STRONG> and <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>: these place the + cursor within and write a character to <STRONG>stdscr</STRONG>, respectively. Frequent changes to the terminal screen can cause unpleasant flicker or - inefficient use of the communication channel to the device, so the - library does not generally update it automatically. Therefore, after + inefficient use of the communication channel to the device, so as a + rule the library does not update it automatically. Therefore, after using <EM>curses</EM> functions to accumulate a set of desired updates that make sense to present together, call <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> to tell the library to make the user's screen look like <STRONG>stdscr</STRONG>. The library <EM>optimizes</EM> its output - by computing a minimal number of operations to mutate the screen from + by computing a minimal volume of operations to mutate the screen from its state at the previous refresh to the new one. Effective optimization demands accurate information about the terminal device: the management of such information is the province of the <STRONG><A HREF="curs_terminfo.3x.html">terminfo(3x)</A></STRONG> API, a feature of every standard <EM>curses</EM> implementation. - Special windows called <EM>pads</EM> may also be manipulated. These are windows - that are not constrained to the size of the terminal screen and whose - contents need not be completely displayed. See <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>. + Special windows called <EM>pads</EM> may also be manipulated. These are not + constrained to the size of the terminal screen and their contents need + not be completely displayed. See <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>. - In addition to drawing characters on the screen, rendering attributes - and colors may be supported, causing the characters to show up in such - modes as underlined, in reverse video, or in color on terminals that - support such display enhancements. See <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>. + Many terminals support configuration of character cell foreground and + background colors as well as <EM>attributes</EM>, which cause characters to + render in such modes as boldfaced, underlined, or in reverse video. + See <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> and <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG>. - <EM>curses</EM> predefines constants for a small set of forms-drawing graphics - corresponding to the DEC Alternate Character Set (ACS), a feature of - VT100 and other terminals. See <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG>. + <EM>curses</EM> defines constants to simplify access to a small set of forms- + drawing graphics corresponding to the DEC Alternate Character Set + (ACS), a feature of VT100 and other terminals. See <STRONG><A HREF="curs_addch.3x.html">addch(3x)</A></STRONG>. - <EM>curses</EM> is implemented using the operating system's terminal driver; - keystroke events are received not as scan codes but as byte sequences. - Graphical keycaps (alphanumeric and punctuation keys, and the space) - appear as-is. Everything else, including the tab, enter/return, - keypad, arrow, and function keys, appears as a control character or a - multibyte <EM>escape</EM> <EM>sequence.</EM> <EM>curses</EM> translates these into unique <EM>key</EM> - <EM>codes.</EM> See <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>. + <EM>curses</EM> is implemented using the operating system's terminal driver; key + events are received not as scan codes but as byte sequences. The + driver reports graphical keycaps (alphanumeric and punctuation keys, + and the space) as-is. Everything else, including the tab, + enter/return, keypad, arrow, and function keys, appears to <EM>curses</EM> as a + control character or a multibyte <EM>escape</EM> <EM>sequence.</EM> <EM>curses</EM> can translate + the latter into unique <EM>key</EM> <EM>codes.</EM> See <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> and <STRONG><A HREF="curs_getch.3x.html">getch(3x)</A></STRONG>. <EM>ncurses</EM> provides reimplementations of the SVr4 <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG>, <STRONG><A HREF="form.3x.html">form(3x)</A></STRONG>, and - <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> libraries to ease construction of user interfaces with <EM>curses</EM>. + <STRONG><A HREF="menu.3x.html">menu(3x)</A></STRONG> libraries; they permit overlapping windows and ease + construction of user interfaces with <EM>curses</EM>. </PRE><H3><a name="h3-Initialization">Initialization</a></H3><PRE> @@ -203,20 +206,20 @@ automatically; <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> may assist with troubleshooting exotic situations. - If you change the terminal type, export the <EM>TERM</EM> environment variable - in the shell, then run <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> or the "<STRONG>tput</STRONG> <STRONG>init</STRONG>" command. See - subsection "Tabs and Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. + If you change the terminal type from a shell, export <EM>TERM</EM>, then run + <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> or the "<STRONG>tput</STRONG> <STRONG>init</STRONG>" command. See subsection "Tabs and + Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. If the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> are set, or if the <EM>curses</EM> program is executing in a graphical windowing environment, the information obtained thence overrides that obtained by <EM>terminfo</EM>. An - <EM>ncurses</EM> extension supports resizable terminals; see <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>. + <EM>ncurses</EM> extension supports resizable terminal displays; see + <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG>. - If the environment variable <EM>TERMINFO</EM> is defined, a <EM>curses</EM> program - checks first for a terminal type description in the location it - identifies. <EM>TERMINFO</EM> is useful for developing experimental type - descriptions or when write permission to <EM>/usr/share/terminfo</EM> is not - available. + If the environment variable <EM>TERMINFO</EM> is defined, a <EM>curses</EM> program + checks first for a terminal type description in the location it + identifies. <EM>TERMINFO</EM> is useful for developing type descriptions or + when write permission to <EM>/usr/share/terminfo</EM> is not available. See section "ENVIRONMENT" below. @@ -226,61 +229,92 @@ alternatives to the name of an elemental one. Those prefixed with "w" require a <EM>WINDOW</EM> pointer argument; those with a "mv" prefix first perform cursor movement using <STRONG><A HREF="curs_move.3x.html">wmove(3x)</A></STRONG>; a "mvw" prefix indicates both. - The "w" function is typically the elemental one; the removal of this + The "w" function is typically the elemental one; the removal of this prefix usually indicates operation on <STRONG>stdscr</STRONG>. - Four functions prefixed with "p" require a pad argument. + Four functions prefixed with "p" require a <EM>pad</EM> argument; see below. - In function synopses, <EM>ncurses</EM> man pages apply the following names to - parameters. + In function synopses, <EM>ncurses</EM> man pages apply the following names to + parameters. We introduce the character types in the next subsection. - <EM>bf</EM> <EM>bool</EM> (<STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>) - <EM>c</EM> a <EM>char</EM> or <EM>int</EM> - <EM>ch</EM> a <EM>chtype</EM> - <EM>wc</EM> a <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> or <EM>wint</EM><STRONG>_</STRONG><EM>t</EM> - <EM>wch</EM> a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> - <EM>win</EM> pointer to a <EM>WINDOW</EM> - <EM>pad</EM> pointer to a <EM>WINDOW</EM> that is a pad + <EM>bf</EM> a <EM>bool</EM> (<STRONG>TRUE</STRONG> or <STRONG>FALSE</STRONG>) + <EM>c</EM> a <EM>char</EM> or <EM>int</EM> + <EM>ch</EM> a <EM>chtype</EM> + <EM>wc</EM> a <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> or <EM>wint</EM><STRONG>_</STRONG><EM>t</EM> + <EM>wch</EM> a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> + <EM>win</EM> pointer to a <EM>WINDOW</EM> + <EM>pad</EM> pointer to a <EM>WINDOW</EM> that is a pad + <EM>pair</EM> a foreground/background color pair identifier </PRE><H3><a name="h3-Wide-and-Non-wide-Character-Configurations">Wide and Non-wide Character Configurations</a></H3><PRE> - This manual page describes functions that appear in any configuration - of the library. There are two common configurations; see section - "ALTERNATE CONFIGURATIONS" below. + This man page primarily surveys functions that appear in any + configuration of the library. There are two common configurations; for + others, see section "ALTERNATE CONFIGURATIONS" below. <EM>ncurses</EM> is the library in its "non-wide" configuration, handling only - eight-bit characters. It stores a character combined with - attributes in a <EM>chtype</EM> datum, which is often an alias of <EM>int</EM>. - - Attributes alone (with no corresponding character) can be - stored in variables of <EM>chtype</EM> or <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> type. In either - case, they are represented as an integral bit mask. - - Each cell of a <EM>WINDOW</EM> is stored as a <EM>chtype</EM>. - - <EM>ncursesw</EM> is the library in its "wide" configuration, which handles + eight-bit characters. It stores a character combined with + attributes and a color pair identifier in a <EM>chtype</EM> datum, + which is often an alias of <EM>int</EM>. A string of <EM>curses</EM> + characters is similar to a C <EM>char</EM> string; a <EM>chtype</EM> string + ends with an integral <STRONG>0</STRONG>, the null <EM>curses</EM> character. + + Attributes and a color pair identifier (with no corresponding + character) can be stored in variables of <EM>chtype</EM> or <EM>attr</EM><STRONG>_</STRONG><EM>t</EM> + type. In either case, they are accessed via an integral bit + mask. + + <EM>ncurses</EM> stores each cell of a <EM>WINDOW</EM> as a <EM>chtype</EM>. X/Open + Curses does not specify the sizes of the character code or + color pair identifier, nor the quantity of attribute bits, in + <EM>chtype</EM>; these are implementation-dependent. <EM>ncurses</EM> uses + eight bits for the character code. An application requiring + a wider character type, for instance to represent Unicode, + should use the wide-character API. + + <EM>ncursesw</EM> is the library in its "wide" configuration, which handles character encodings requiring a larger data type than <EM>char</EM> (a - byte-sized type) can represent. It adds about one third more - calls using additional data types that can store such - <EM>multibyte</EM> characters. - - <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> corresponds to the non-wide configuration's <EM>chtype</EM>. - It always a structure type, because it stores more - data than fit into a standard scalar type. A - character code may not be representable as a <EM>char</EM>, - and moreover more than one character may occupy a - cell (as with accent marks and other diacritics). - Each character is of type <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>; a complex - character contains one spacing character and zero or - more non-spacing characters (see below). Attributes - and color data are stored in separate fields of the - structure, not combined as in <EM>chtype</EM>. - - Each cell of a <EM>WINDOW</EM> is stored as a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. + byte-sized type) can represent. It provides additional + functions that complement those in the non-wide library where + the size of the underlying character type is significant. A + somewhat regular naming convention relates many of the wide + variants to their non-wide counterparts; where a non-wide + function name contains "ch" or "str", prefix it with "_w" to + obtain the wide counterpart. For example, <STRONG>waddch</STRONG> becomes + <STRONG>wadd_wch</STRONG>. An exception is <STRONG>ins_nwstr</STRONG> (and its variants), + spelled thus instead of "insn_wstr". (Exceptions that add + only "w" comprise <STRONG>addwstr</STRONG>, <STRONG>inwstr</STRONG>, and their variants.) + + This convention is inapplicable to some non-wide function + names, so other transformations are used for the wide + configuration: the window background management function + "bkgd" becomes "bkgrnd"; the window border-drawing and + -clearing functions are suffixed with "_set"; and character + attribute manipulation functions like "attron" become + "attr_on". + <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> is a <EM>curses</EM> <EM>complex</EM> <EM>character</EM> and corresponds to the + non-wide-character configuration's <EM>chtype</EM>. It is a + structure type because it requires more storage than + a standard scalar type offers. A character code may + not be representable as a <EM>char</EM>, and moreover more + than one character may occupy a cell (as with accent + marks and other diacritics). Each character is of + type <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM>; a complex character contains one + spacing character and zero or more non-spacing + characters (see below). A string of complex + characters ends with a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> whose <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> member + is the null wide character. Attributes and a color + pair identifier are stored in separate fields of the + structure, not combined into an integer as in + <EM>chtype</EM>. + + <EM>ncurses</EM> stores each cell of a <EM>WINDOW</EM> as a <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM>. <STRONG><A HREF="curs_getcchar.3x.html">setcchar(3x)</A></STRONG> and <STRONG><A HREF="curs_getcchar.3x.html">getcchar(3x)</A></STRONG> store and retrieve <EM>cchar</EM><STRONG>_</STRONG><EM>t</EM> - data. The wide library API of <EM>ncurses</EM> depends on two data - types standardized by ISO C95. + data. + + The wide library API of <EM>ncurses</EM> depends on two data types + standardized by ISO C95. <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> stores a wide character. Like <EM>chtype</EM>, it may be an alias of <EM>int</EM>. Depending on the character encoding, @@ -292,36 +326,18 @@ base glyph with which it combines, and typically does not advance the cursor. - <EM>wint</EM><STRONG>_</STRONG><EM>t</EM> can store a <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> or the constant <STRONG>WEOF</STRONG>, + <EM>wint</EM><STRONG>_</STRONG><EM>t</EM> can store a <EM>wchar</EM><STRONG>_</STRONG><EM>t</EM> or the constant <EM>WEOF</EM>, analogously to the <EM>int</EM>-sized character manipulation - functions of ISO C and its constant <STRONG>EOF</STRONG>. - - The wide library provides additional functions that - complement those in the non-wide library where the size of - the underlying character type is significant. A somewhat - regular naming convention relates many of the wide variants - to their non-wide counterparts; where a non-wide function - name contains "ch" or "str", prefix it with "_w" to obtain - the wide counterpart. For example, <STRONG>waddch</STRONG> becomes <STRONG>wadd_wch</STRONG>. - (Exceptions that add only "w" comprise <STRONG>addwstr</STRONG>, <STRONG>inwstr</STRONG>, and - their variants.) - - This convention is inapplicable to some non-wide function - names, so other transformations are used for the wide - configuration: the window background management function - "bkgd" becomes "bkgrnd"; the window border-drawing and - -clearing functions are suffixed with "_set"; and character - attribute manipulation functions like "attron" become - "attr_on". + functions of ISO C and its constant <EM>EOF</EM>. </PRE><H3><a name="h3-Function-Name-Index">Function Name Index</a></H3><PRE> The following table lists the <EM>curses</EM> functions provided in the non-wide - and wide APIs and the corresponding man pages that describe them. - Those flagged with "*" are <EM>ncurses</EM>-specific, neither described by + and wide APIs and the corresponding man pages that describe them. + Those flagged with "*" are <EM>ncurses</EM>-specific, neither described by X/Open Curses nor present in SVr4. - <STRONG><EM>curses</EM></STRONG> Function Name Man Page + <EM>curses</EM> Function Name Man Page --------------------------------------------- COLOR_PAIR <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> PAIR_NUMBER <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> @@ -380,7 +396,6 @@ doupdate <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG> dupwin <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG> echo <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> - echo_wchar <STRONG><A HREF="curs_add_wch.3x.html">curs_add_wch(3x)</A></STRONG> echochar <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG> endwin <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> @@ -446,7 +461,6 @@ init_pair <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> initscr <STRONG><A HREF="curs_initscr.3x.html">curs_initscr(3x)</A></STRONG> innstr <STRONG><A HREF="curs_instr.3x.html">curs_instr(3x)</A></STRONG> - innwstr <STRONG><A HREF="curs_inwstr.3x.html">curs_inwstr(3x)</A></STRONG> ins_nwstr <STRONG><A HREF="curs_ins_wstr.3x.html">curs_ins_wstr(3x)</A></STRONG> ins_wch <STRONG><A HREF="curs_ins_wch.3x.html">curs_ins_wch(3x)</A></STRONG> @@ -506,13 +520,12 @@ mvaddstr <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG> mvaddwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG> mvchgat <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> - mvcur <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> + mvcur <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> mvdelch <STRONG><A HREF="curs_delch.3x.html">curs_delch(3x)</A></STRONG> mvderwin <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG> mvget_wch <STRONG><A HREF="curs_get_wch.3x.html">curs_get_wch(3x)</A></STRONG> mvget_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> mvgetch <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG> - mvgetn_wstr <STRONG><A HREF="curs_get_wstr.3x.html">curs_get_wstr(3x)</A></STRONG> mvgetnstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> mvgetstr <STRONG><A HREF="curs_getstr.3x.html">curs_getstr(3x)</A></STRONG> @@ -578,7 +591,6 @@ mvwprintw <STRONG><A HREF="curs_printw.3x.html">curs_printw(3x)</A></STRONG> mvwscanw <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG> mvwvline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> - mvwvline_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG> napms <STRONG><A HREF="curs_kernel.3x.html">curs_kernel(3x)</A></STRONG> newpad <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> @@ -644,7 +656,6 @@ slk_init <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> slk_label <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> slk_noutrefresh <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> - slk_refresh <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> slk_restore <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> slk_set <STRONG><A HREF="curs_slk.3x.html">curs_slk(3x)</A></STRONG> @@ -710,7 +721,6 @@ waddnwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG> waddstr <STRONG><A HREF="curs_addstr.3x.html">curs_addstr(3x)</A></STRONG> waddwstr <STRONG><A HREF="curs_addwstr.3x.html">curs_addwstr(3x)</A></STRONG> - wattr_get <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> wattr_off <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> wattr_on <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> @@ -776,7 +786,6 @@ wscanw <STRONG><A HREF="curs_scanw.3x.html">curs_scanw(3x)</A></STRONG> wscrl <STRONG><A HREF="curs_scroll.3x.html">curs_scroll(3x)</A></STRONG> wsetscrreg <STRONG><A HREF="curs_outopts.3x.html">curs_outopts(3x)</A></STRONG> - wstandend <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> wstandout <STRONG><A HREF="curs_attr.3x.html">curs_attr(3x)</A></STRONG> wsyncdown <STRONG><A HREF="curs_window.3x.html">curs_window(3x)</A></STRONG> @@ -787,38 +796,40 @@ wvline <STRONG><A HREF="curs_border.3x.html">curs_border(3x)</A></STRONG> wvline_set <STRONG><A HREF="curs_border_set.3x.html">curs_border_set(3x)</A></STRONG> - <EM>ncurses</EM>'s <EM>screen-pointer</EM> <EM>extension</EM> adds additional functions - corresponding to many of the above, each with an "_sp" suffix; see + <EM>ncurses</EM>'s <EM>screen-pointer</EM> <EM>extension</EM> adds additional functions + corresponding to many of the above, each with an "_sp" suffix; see <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>. - The availability of some extensions is configurable when <EM>ncurses</EM> is - compiled; see sections "ALTERNATE CONFIGURATIONS" and "EXTENSIONS" + The availability of some extensions is configurable when <EM>ncurses</EM> is + compiled; see sections "ALTERNATE CONFIGURATIONS" and "EXTENSIONS" below. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Unless otherwise noted, functions that return an integer return <STRONG>OK</STRONG> on - success and <STRONG>ERR</STRONG> on failure. Functions that return pointers return <STRONG>NULL</STRONG> - on failure. Typically, <EM>ncurses</EM> treats a null pointer passed as a - function parameter as a failure. Functions prefixed with "mv" first - perform cursor movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the - window boundaries. + Unless otherwise noted, functions that return integers return the + constants <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure; see <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>. + Functions that return pointers return a null pointer on failure. + Typically, <EM>ncurses</EM> treats a null pointer passed as a function parameter + as a failure. Functions prefixed with "mv" first perform cursor + movement and fail if the position (<EM>y</EM>, <EM>x</EM>) is outside the window + boundaries. </PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE> - The following symbols from the process environment customize the - runtime behavior of <EM>ncurses</EM> applications. The library may be - configured to disregard the variables <EM>TERMINFO</EM>, <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM>, - <EM>TERMPATH</EM>, and <EM>HOME</EM>, if the user is the superuser (root), or the + The following symbols from the process environment customize the + runtime behavior of <EM>ncurses</EM> applications. The library may be + configured to disregard the variables <EM>TERMINFO</EM>, <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM>, + <EM>TERMPATH</EM>, and <EM>HOME</EM>, if the user is the superuser (root), or the application uses <STRONG>setuid(2)</STRONG> or <STRONG>setgid(2)</STRONG>. </PRE><H3><a name="h3-BAUDRATE"><EM>BAUDRATE</EM></a></H3><PRE> - The debugging library checks this variable when the application has - redirected output to a file. Its integral value is used for the baud - rate. If that value is absent or invalid, <EM>ncurses</EM> uses 9600. This - feature allows testers to construct repeatable test cases that take - into account optimization decisions that depend on baud rate. + The debugging library checks this variable when the application has + redirected output to a file. <EM>ncurses</EM> interprets its integral value as + the terminal's line speed in bits per second. If that value is absent + or invalid, <EM>ncurses</EM> uses 9600. This feature allows developers to + construct repeatable test cases that take into account optimization + decisions that depend on the terminal's line speed. </PRE><H3><a name="h3-CC-_command-character_"><EM>CC</EM> (command character)</a></H3><PRE> @@ -826,16 +837,17 @@ <EM>terminfo</EM> entries changes to the value of this variable. Very few <EM>term-</EM> <EM>info</EM> entries provide this feature. - Because this name is also used in development environments to represent - the C compiler's name, <EM>ncurses</EM> ignores its value if it is not one - character in length. + Because this name is also used in development environments to store the + C compiler's name, <EM>ncurses</EM> ignores its value if it is not one character + in length. </PRE><H3><a name="h3-COLUMNS"><EM>COLUMNS</EM></a></H3><PRE> - This variable specifies the width of the screen in characters. - Applications running in a windowing environment usually are able to - obtain the width of the window in which they are executing. If <EM>COLUMNS</EM> - is not defined and the terminal's screen size is not available from the + This variable specifies the width of the screen in character cells. + Applications running in a windowing environment usually are able to + obtain the width of the window in which they are executing. <EM>ncurses</EM> + enforces an upper limit of 512 when reading the value. If <EM>COLUMNS</EM> is + not defined and the terminal's screen size is not available from the terminal driver, <EM>ncurses</EM> uses the size specified by the <STRONG>columns</STRONG> (<STRONG>cols</STRONG>) capability of the terminal type's entry in the <EM>terminfo</EM> database, if any. @@ -863,17 +875,20 @@ For <EM>curses</EM> to distinguish the ESC character resulting from a user's press of the "Escape" key on the input device from one beginning an <EM>escape</EM> <EM>sequence</EM> (as commonly produced by function keys), it waits after - receiving the escape character to see if further characters are - available on the input stream within a short interval. A global - variable <STRONG>ESCDELAY</STRONG> stores this interval in milliseconds. The default + receiving the escape character to see if further characters are + available on the input stream within a short interval. A global + variable <STRONG>ESCDELAY</STRONG> stores this interval in milliseconds. The default value of 1000 (one second) is adequate for most uses. This environment - variable overrides it. + variable overrides it; <EM>ncurses</EM> enforces an upper limit of 30,000 (30 + seconds) when reading the value. - The most common instance where you may wish to change this value is to + The most common instance where you may wish to change this value is to work with a remote host over a slow communication channel. If the host running a <EM>curses</EM> application does not receive the characters of an escape sequence in a timely manner, the library can interpret them as - multiple key stroke events. + multiple key stroke events. Conversely, a fast typist on a low-latency + connection who happens to input an ESC followed by characters that + match an escape sequence may experience confusing application behavior. <STRONG>xterm(1)</STRONG> mouse events are a form of escape sequence; therefore, if your application makes heavy use of multiple-clicking, you may wish to @@ -884,8 +899,9 @@ either form, but setting the environment variable rather than the global variable does not create problems when compiling an application. - If <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> is disabled for the <EM>curses</EM> window receiving input, a - program must disambiguate escape sequences itself. + If <STRONG><A HREF="curs_inopts.3x.html">keypad(3x)</A></STRONG> is disabled for the <EM>curses</EM> window receiving input, + <STRONG>ESCDELAY</STRONG> is irrelevant and a program must disambiguate escape sequences + itself. </PRE><H3><a name="h3-HOME"><EM>HOME</EM></a></H3><PRE> @@ -917,8 +933,10 @@ For example, to tell <EM>ncurses</EM> not to assume anything about the colors, use a value of "-1,-1". To make the default color scheme green on - black, use "2,0". <EM>ncurses</EM> accepts integral values from -1 up to the - value of the <EM>terminfo</EM> <STRONG>max_colors</STRONG> (<STRONG>colors</STRONG>) capability. + black on a terminal that uses ANSI X3.64/ECMA-48/ISO 6429 color + assignments, use "2,0". <EM>ncurses</EM> accepts integral values from -1 up to + the value of the <EM>terminfo</EM> <STRONG>max_colors</STRONG> (<STRONG>colors</STRONG>) capability for the + selected terminal type. </PRE><H3><a name="h3-NCURSES_CONSOLE2"><EM>NCURSES_CONSOLE2</EM></a></H3><PRE> @@ -932,29 +950,31 @@ </PRE><H3><a name="h3-NCURSES_GPM_TERMS"><EM>NCURSES_GPM_TERMS</EM></a></H3><PRE> (Linux only) When <EM>ncurses</EM> is configured to use the GPM interface, this - variable may list one or more terminal names against which the <EM>TERM</EM> - variable (see below) is matched. An empty value disables the GPM - interface, using <EM>ncurses</EM>'s built-in support for <STRONG>xterm(1)</STRONG> mouse - protocols instead. If the variable is absent, <EM>ncurses</EM> attempts to open - GPM if <EM>TERM</EM> contains "linux". + variable may list one or more terminal type names, delimited by + vertical bars (<STRONG>|</STRONG>) or colons (<STRONG>:</STRONG>), against which the <EM>TERM</EM> variable (see + below) is matched. An empty value disables the GPM interface, using + <EM>ncurses</EM>'s built-in support for <STRONG>xterm(1)</STRONG> mouse protocols instead. If + the variable is absent, <EM>ncurses</EM> attempts to open GPM if <EM>TERM</EM> contains + "linux". </PRE><H3><a name="h3-NCURSES_NO_HARD_TABS"><EM>NCURSES_NO_HARD_TABS</EM></a></H3><PRE> - <EM>ncurses</EM> may use tab characters in cursor movement optimization. In - some cases, your terminal driver may not handle them properly. Set + <EM>ncurses</EM> may use tab characters in cursor movement optimization. In + some cases, your terminal driver may not handle them properly. Set this environment variable to any value to disable the feature. You can also adjust your <STRONG>stty(1)</STRONG> settings to avoid the problem. </PRE><H3><a name="h3-NCURSES_NO_MAGIC_COOKIE"><EM>NCURSES_NO_MAGIC_COOKIE</EM></a></H3><PRE> - Many terminals store video attributes as a property of a character + Many terminals store video attributes as properties of a character cell, as <EM>curses</EM> does. Historically, some recorded changes in video - attributes as data that logically <EM>occupies</EM> character cells on the - display, switching attributes on or off, similarly to tags in a markup - language; these are termed "magic cookies", and must be subsequently - overprinted. If the <EM>terminfo</EM> entry for your terminal type does not - adequately describe its handling of magic cookies, set this variable to - any value to instruct <EM>ncurses</EM> to disable attributes entirely. + attributes as data that logically (but invisibly) <EM>occupied</EM> character + cells on the display, switching attributes on or off, similarly to tags + in a markup language, which then had to be overprinted to depict the + cells' desired contents; these are termed "magic cookies". If the + <EM>terminfo</EM> entry for your terminal type does not adequately describe its + handling of magic cookies, set this variable to any value to instruct + <EM>ncurses</EM> to disable attributes entirely. </PRE><H3><a name="h3-NCURSES_NO_PADDING"><EM>NCURSES_NO_PADDING</EM></a></H3><PRE> @@ -964,47 +984,49 @@ programs can duplicate all of the important features of a hardware terminal, but often lack their limitations. Chief among these absent drawbacks is the problem of data flow management; that is, limiting the - speed of communication to what the hardware could handle. Unless a - hardware terminal is interfaced into a terminal concentrator (which - does flow control), an application must manage flow control itself to - prevent overruns and data loss. - - A solution that comes at no hardware cost is for an application to - pause after directing a terminal to execute an operation that it - performs slowly, such as clearing the display. Many terminal type - descriptions, including that for the VT100, embed delay specifications - in capabilities. You may wish to use these terminal descriptions - without paying the performance penalty. Set <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>PADDING</EM> to any - value to disable all but mandatory padding. Mandatory padding is used - by such terminal capabilities as <STRONG>flash_screen</STRONG> (<STRONG>flash</STRONG>). + speed of communication to what the hardware could handle. Unless a + hardware terminal is interfaced into a terminal concentrator (which + does flow control), an application must manage flow itself to prevent + overruns and data loss. + + A solution that comes at no hardware cost is for an application to + pause transmission after directing a terminal to execute an operation + that it performs slowly, such as clearing the display. Many terminal + type descriptions, including that for the VT100, embed delay + specifications in capabilities. You may wish to use these terminal + descriptions without paying the performance penalty. Set + <EM>NCURSES</EM><STRONG>_</STRONG><EM>NO</EM><STRONG>_</STRONG><EM>PADDING</EM> to any value to disable all but mandatory padding. + Mandatory padding is used by such terminal capabilities as <STRONG>flash_screen</STRONG> + (<STRONG>flash</STRONG>). </PRE><H3><a name="h3-NCURSES_NO_SETBUF"><EM>NCURSES_NO_SETBUF</EM></a></H3><PRE> - (Obsolete) Prior to internal changes developed in <EM>ncurses</EM> 5.9 (patches - 20120825 through 20130126), the library used <STRONG>setbuf(3)</STRONG> to enable fully - buffered output when initializing the terminal. This was done, as in - SVr4 <EM>curses</EM>, to increase performance. For testing purposes, both of - <EM>ncurses</EM> and of certain applications, this feature was made optional. - Setting this variable disabled output buffering, leaving the output + (Obsolete) Prior to internal changes developed in <EM>ncurses</EM> 5.9 (patches + 20120825 through 20130126), the library used <STRONG>setbuf(3)</STRONG> to enable fully + buffered output when initializing the terminal. This was done, as in + SVr4 <EM>curses</EM>, to increase performance. For testing purposes, both of + <EM>ncurses</EM> and of certain applications, this feature was made optional. + Setting this variable disabled output buffering, leaving the output stream in the original (usually line-buffered) mode. - Nowadays, <EM>ncurses</EM> performs its own buffering and does not require this - workaround; it does not modify the buffering of the standard output - stream. This approach makes signal handling, as for interrupts, more - robust. A drawback is that certain unconventional programs mixed - <STRONG>stdio(3)</STRONG> calls with <EM>ncurses</EM> calls and (usually) got the behavior they - expected. This is no longer the case; <EM>ncurses</EM> does not write to the - standard output file descriptor through a <EM>stdio</EM>-buffered stream. - - As a special case, low-level API calls such as <STRONG><A HREF="curs_terminfo.3x.html">putp(3x)</A></STRONG> still use the - standard output stream. High-level <EM>curses</EM> calls such as <STRONG><A HREF="curs_printw.3x.html">printw(3x)</A></STRONG> do + Nowadays, <EM>ncurses</EM> performs its own buffering and does not require this + workaround; it does not modify the buffering of the standard output + stream. This approach makes the library's handling of keyboard- + initiated signals more robust. A drawback is that certain + unconventional programs mixed <STRONG>stdio(3)</STRONG> calls with <EM>ncurses</EM> calls and + (usually) got the behavior they expected. This is no longer the case; + <EM>ncurses</EM> does not write to the standard output file descriptor through a + <EM>stdio</EM>-buffered stream. + + As a special case, low-level API calls such as <STRONG><A HREF="curs_terminfo.3x.html">putp(3x)</A></STRONG> still use the + standard output stream. High-level <EM>curses</EM> calls such as <STRONG><A HREF="curs_printw.3x.html">printw(3x)</A></STRONG> do not. </PRE><H3><a name="h3-NCURSES_NO_UTF8_ACS"><EM>NCURSES_NO_UTF8_ACS</EM></a></H3><PRE> - At initialization, <EM>ncurses</EM> inspects the <EM>TERM</EM> environment variable for - special cases where VT100 forms-drawing characters (and the - corresponding alternate character set <EM>terminfo</EM> capabilities) are known + At initialization, <EM>ncurses</EM> inspects the <EM>TERM</EM> environment variable for + special cases where VT100 forms-drawing characters (and the + corresponding alternate character set <EM>terminfo</EM> capabilities) are known to be unsupported by terminal types that otherwise claim VT100 compatibility. Specifically, when running in a UTF-8 locale, the Linux virtual console device and the GNU <STRONG>screen(1)</STRONG> program ignore them. Set @@ -1012,10 +1034,10 @@ terminal's ACS support is broken; the library then outputs Unicode code points that correspond to the forms-drawing characters. Set it to zero (or a non-integer) to disable the special check for terminal type names - matching "linux" or "screen", directing <EM>ncurses</EM> to assume that the ACS + matching "linux" or "screen", directing <EM>ncurses</EM> to assume that the ACS feature works if the terminal type description advertises it. - As an alternative to use of this variable, <EM>ncurses</EM> checks for an + As an alternative to use of this variable, <EM>ncurses</EM> checks for an extended <EM>terminfo</EM> numeric capability <STRONG>U8</STRONG> that can be compiled using "<STRONG>tic</STRONG> <STRONG>-x</STRONG>". Examples follow. @@ -1071,8 +1093,8 @@ the default location. <STRONG>o</STRONG> Descriptions in <EM>terminfo</EM> format are normally stored in a directory - tree using subdirectories named by the common first letters of the - terminal types named therein. This is the scheme used in System V. + tree using subdirectories named for the common first letters of the + terminal types named therein. System V used this scheme. <STRONG>o</STRONG> If <EM>ncurses</EM> is configured to use hashed databases, then <EM>TERMINFO</EM> may name its location, such as <EM>/usr/share/terminfo.db</EM>, rather than @@ -1080,8 +1102,7 @@ The hashed database uses less disk space and is a little faster than the directory tree. However, some applications assume the existence of - the directory tree, and read it directly rather than using the <EM>terminfo</EM> - API. + the directory tree and read it directly, ignoring the <EM>terminfo</EM> API. <STRONG>o</STRONG> If <EM>ncurses</EM> is configured with <EM>termcap</EM> support, this variable may contain the location of a <EM>termcap</EM> file. @@ -1093,10 +1114,10 @@ TERMINFO=$(infocmp -0 -Q2 -q) export TERMINFO - The compiled description is used only if it corresponds to the + <EM>ncurses</EM> uses the compiled description only if it corresponds to the terminal type identified by <EM>TERM</EM>. - Setting <EM>TERMINFO</EM> is the simplest, but not the only, way to direct + Setting <EM>TERMINFO</EM> is the simplest, but not the only, way to direct <EM>ncurses</EM> to a terminal database. The search path is as follows. <STRONG>o</STRONG> the last terminal database to which the running <EM>ncurses</EM> application @@ -1110,7 +1131,7 @@ <STRONG>o</STRONG> location(s) configured and compiled into <EM>ncurses</EM> - <STRONG>o</STRONG> <EM>/usr/share/terminfo</EM> + <STRONG>o</STRONG> <EM>/usr/share/terminfo</EM> </PRE><H3><a name="h3-TERMINFO_DIRS"><EM>TERMINFO_DIRS</EM></a></H3><PRE> @@ -1123,7 +1144,7 @@ </PRE><H3><a name="h3-TERMPATH"><EM>TERMPATH</EM></a></H3><PRE> If <EM>TERMCAP</EM> does not hold a terminal type description or file name, then - <EM>ncurses</EM> checks the contents of <EM>TERMPATH</EM>, a list of locations, akin to + <EM>ncurses</EM> checks the contents of <EM>TERMPATH</EM>, a list of locations, akin to <EM>PATH</EM>, in which it searches for <EM>termcap</EM> terminal type descriptions. The list items are separated by colons on Unix and semicolons on OS/2 EMX. @@ -1139,93 +1160,103 @@ particular significance to the application developer employing <EM>ncurses</EM>. <STRONG>--disable-overwrite</STRONG> - The standard include for <EM>ncurses</EM> is as noted in <STRONG>SYNOPSIS</STRONG>: + Avoid file name conflicts between <EM>ncurses</EM> and an existing <EM>curses</EM> + installation on the system. The standard C preprocessor inclusion + for the <EM>curses</EM> library is as follows. <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - This option is used to avoid filename conflicts when <EM>ncurses</EM> is - not the main implementation of curses of the computer. If <EM>ncurses</EM> - is installed disabling overwrite, it puts its headers in a - subdirectory, e.g., + If <EM>ncurses</EM> is installed disabling overwrite, it puts its header + files in a subdirectory. Here is an example. <STRONG>#include</STRONG> <STRONG><ncurses/curses.h></STRONG> - It also omits a symbolic link which would allow you to use - <STRONG>-lcurses</STRONG> to build executables. + With <STRONG>--disable-overwrite</STRONG>, installation also omits a symbolic link + that would cause the compiler's <STRONG>-lcurses</STRONG> option to link object + files with <EM>ncurses</EM> instead of the system <EM>curses</EM> library. - <STRONG>--enable-widec</STRONG> - The configure script renames the library and (if the - <STRONG>--disable-overwrite</STRONG> option is used) puts the header files in a - different subdirectory. All of the library names have a "w" - appended to them, i.e., instead of - - <STRONG>-lncurses</STRONG> - - you link with - - <STRONG>-lncursesw</STRONG> - - You must also enable the wide-character features in the header - file when compiling for the wide-character library to use the - extended (wide-character) functions. The symbol which enables - these features has changed since X/Open Curses, Issue 4: + The directory used by this configuration of <EM>ncurses</EM> is shown in + section "SYNOPSIS" above. - <STRONG>o</STRONG> Originally, the wide-character feature required the symbol - <STRONG>_XOPEN_SOURCE_EXTENDED</STRONG> but that was only valid for XPG4 + <STRONG>--enable-widec</STRONG> + (default for ABI 6+ since 2023-10-21) Enable support for wide + characters. The <EM>configure</EM> script renames the <EM>ncurses</EM> library (and + the <EM>tinfo</EM> library, if <STRONG>--with-termlib</STRONG> is also specified), appending + "w". An application desirous of wide-character support then uses + <STRONG>-lncursesw</STRONG> (or <STRONG>-ltinfow</STRONG>) instead of <STRONG>-lncurses</STRONG> (or <STRONG>-ltinfo</STRONG>) as its + linker option. The <EM>ncurses++</EM>, <EM>panel</EM>, <EM>form</EM>, and <EM>menu</EM> libraries are + renamed similarly. + + An application must also define certain C preprocessor symbols to + enable wide-character features in <EM>curses</EM> header files to use the + extended (wide-character) functions. The symbol that enables + these features has changed since X/Open Curses Issue 4. + + <STRONG>o</STRONG> Originally, the wide-character feature required the symbol + <STRONG>_</STRONG><EM>XOPEN</EM><STRONG>_</STRONG><EM>SOURCE</EM><STRONG>_</STRONG><EM>EXTENDED</EM>, but that was valid only for XPG4 (1996). - <STRONG>o</STRONG> Later, that was deemed conflicting with <STRONG>_XOPEN_SOURCE</STRONG> defined - to 500. + <STRONG>o</STRONG> Later, that was deemed conflicting with an <STRONG>_</STRONG><EM>XOPEN</EM><STRONG>_</STRONG><EM>SOURCE</EM> value + of 500. - <STRONG>o</STRONG> As of mid-2018, none of the features in this implementation - require a <STRONG>_XOPEN_SOURCE</STRONG> feature greater than 600. However, - X/Open Curses, Issue 7 (2009) recommends defining it to 700. + <STRONG>o</STRONG> As of mid-2018, no <EM>ncurses</EM> feature requires a <STRONG>_</STRONG><EM>XOPEN</EM><STRONG>_</STRONG><EM>SOURCE</EM> + value greater than 600. However, X/Open Curses Issue 7 (2009) + recommends defining it to 700. - <STRONG>o</STRONG> Alternatively, you can enable the feature by defining - <STRONG>NCURSES_WIDECHAR</STRONG> with the caveat that some other header file - than <STRONG>curses.h</STRONG> may require a specific value for <STRONG>_XOPEN_SOURCE</STRONG> + <STRONG>o</STRONG> Alternatively, you can enable the feature by defining + <STRONG>NCURSES_WIDECHAR</STRONG> with the caveat that some header file other + than <EM>curses.h</EM> may require a specific value for <STRONG>_</STRONG><EM>XOPEN</EM><STRONG>_</STRONG><EM>SOURCE</EM> (or a system-specific symbol). - The <EM>curses.h</EM> header file installed for the wide-character library - is designed to be compatible with the non-wide library's header. - Only the size of the <EM>WINDOW</EM> structure differs; few applications - require more than pointers to <EM>WINDOW</EM>s. + The <EM>curses.h</EM> header file installed for the wide-character library + is designed to be compatible with the non-wide library's header. + Only the size of the <EM>WINDOW</EM> structure differs; few applications + require more than pointers to <EM>WINDOW</EM>. - If the headers are installed allowing overwrite, the wide- - character library's headers should be installed last, to allow - applications to be built using either library from the same set of - headers. + If <EM>ncurses</EM>'s header files are installed allowing overwrite (the + default, but see <STRONG>--disable-overwrite</STRONG> above), the wide-character + library's headers should be installed last by packaging systems + and similar, to allow applications to be built using either + library from the same set of headers. <STRONG>--with-pthread</STRONG> - The configure script renames the library. All of the library - names have a "t" appended to them (before any "w" added by - <STRONG>--enable-widec</STRONG>). - - The global variables such as <STRONG>LINES</STRONG> are replaced by macros to allow - read-only access. At the same time, setter-functions are provided - to set these values. Some applications (very few) may require + Enable support for multi-threaded applications. The <EM>configure</EM> + script renames the <EM>ncurses</EM> library (and the <EM>tinfo</EM> library, if + <STRONG>--with-termlib</STRONG> is also specified), appending "t" (before any "w" + added by <STRONG>--enable-widec</STRONG>). An application desirous of support for + multiple threads of execution then uses, for example, <STRONG>-lncursest</STRONG> + (or <STRONG>-ltinfot</STRONG>) instead of <STRONG>-lncurses</STRONG> (or <STRONG>-ltinfo</STRONG>) as its linker + option. The <EM>ncurses++</EM>, <EM>panel</EM>, <EM>form</EM>, and <EM>menu</EM> libraries are + renamed similarly. + + <EM>ncursest</EM> and <EM>ncursestw</EM> replace global variables such as <STRONG>LINES</STRONG> with + macros allowing read-only access. At the same time, they provide + functions to set these values. Very few applications require changes to work with this convention. <STRONG>--with-shared</STRONG> <STRONG>--with-normal</STRONG> <STRONG>--with-debug</STRONG> <STRONG>--with-profile</STRONG> - The shared and normal (static) library names differ by their - suffixes, e.g., <STRONG>libncurses.so</STRONG> and <STRONG>libncurses.a</STRONG>. The debug and - profiling libraries add a "_g" and a "_p" to the root names - respectively, e.g., <STRONG>libncurses_g.a</STRONG> and <STRONG>libncurses_p.a</STRONG>. + Mandate compilation of the <EM>ncurses</EM> library (and the <EM>tinfo</EM> library, + if <STRONG>--with-termlib</STRONG> is also specified) in the specified forms. The + shared and normal (static) library names differ by their suffixes, + as with <EM>libncurses.so</EM> and <EM>libncurses.a</EM>. The debugging and + profiling libraries add a "_g" and a "_p" to the roots of these + respective names, forming <EM>libncurses</EM><STRONG>_</STRONG><EM>g.so</EM> and <EM>libncurses</EM><STRONG>_</STRONG><EM>p.a</EM>, for + example. The <EM>ncurses++</EM>, <EM>panel</EM>, <EM>form</EM>, and <EM>menu</EM> libraries are made + available similarly. <STRONG>--with-termlib</STRONG> - Low-level functions which do not depend upon whether the library - supports wide-characters, are provided in the tinfo library. - - By doing this, it is possible to share the tinfo library between - wide/normal configurations as well as reduce the size of the - library when only low-level functions are needed. + Provide <EM>ncurses</EM>'s lower-level terminal interface functions (those + that do not depend on the <EM>SCREEN</EM> and <EM>WINDOW</EM> abstractions) in a + library named <EM>tinfo</EM>. This arrangement reduces an application's + linking and/or loading times when it does not require <EM>curses</EM>'s + higher-level features. - Those functions are described in these pages: + The following pages document <EM>curses</EM> functions provided by <EM>tinfo</EM>. - <STRONG>o</STRONG> <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG> - miscellaneous <EM>curses</EM> extensions + <STRONG>o</STRONG> <STRONG><A HREF="curs_extend.3x.html">curs_extend(3x)</A></STRONG> - miscellaneous <EM>ncurses</EM> extensions <STRONG>o</STRONG> <STRONG><A HREF="curs_inopts.3x.html">curs_inopts(3x)</A></STRONG> - <EM>curses</EM> input options @@ -1240,10 +1271,13 @@ <STRONG>o</STRONG> <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> - miscellaneous <EM>curses</EM> utility routines <STRONG>--with-trace</STRONG> - The <STRONG>trace</STRONG> function normally resides in the debug library, but it - is sometimes useful to configure this in the shared library. - Configure scripts should check for the function's existence rather - than assuming it is always in the debug library. + Expose the <STRONG><A HREF="curs_trace.3x.html">curses_trace(3x)</A></STRONG> function in the <EM>ncurses(w)</EM> shared and + static libraries. Normally, it is available only in the debugging + library. (If <STRONG>--with-termlib</STRONG> is also specified, <EM>tinfo(w)</EM> rather + than <EM>ncurses(w)</EM> supplies the deprecated <STRONG><A HREF="curs_trace.3x.html">trace(3x)</A></STRONG> function.) An + application's configuration script should check for the function's + existence rather than assuming its confinement to the debugging + library. </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE> @@ -1265,7 +1299,7 @@ <STRONG>o</STRONG> to reuse functions (for example, those that move the cursor before another operation), and - <STRONG>o</STRONG> a few special cases. + <STRONG>o</STRONG> in a few special cases. If the standard output file descriptor of an <EM>ncurses</EM> program is redirected to something that is not a terminal device, the library @@ -1277,7 +1311,7 @@ </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - <EM>ncurses</EM> enables an application to capture mouse events on certain + <EM>ncurses</EM> enables an application to capture mouse events from certain terminals, including <STRONG>xterm(1)</STRONG>; see <STRONG><A HREF="curs_mouse.3x.html">curs_mouse(3x)</A></STRONG>. <EM>ncurses</EM> provides a means of responding to window resizing events, as @@ -1299,40 +1333,40 @@ to draw colored text on a background whose color is set independently, providing better control over color contrasts. See <STRONG><A HREF="default_colors.3x.html">default_colors(3x)</A></STRONG>. - An <EM>ncurses</EM> application can eschew knowledge of <EM>WINDOW</EM> structure - internals, instead using accessor functions such as <STRONG><A HREF="curs_opaque.3x.html">is_scrollok(3x)</A></STRONG>. + An <EM>ncurses</EM> application can eschew knowledge of <EM>SCREEN</EM> and <EM>WINDOW</EM> + structure internals, instead using accessor functions such as + <STRONG><A HREF="curs_inopts.3x.html">is_cbreak(3x)</A></STRONG> and <STRONG><A HREF="curs_opaque.3x.html">is_scrollok(3x)</A></STRONG>. - <EM>ncurses</EM> enables an application to direct application output to a - printer attached to the terminal device; see <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>. + <EM>ncurses</EM> enables an application to direct its output to a printer + attached to the terminal device; see <STRONG><A HREF="curs_print.3x.html">curs_print(3x)</A></STRONG>. - <EM>ncurses</EM> offers <STRONG><A HREF="curs_slk.3x.html">slk_attr(3x)</A></STRONG> as a counterpart of <STRONG><A HREF="curs_attr.3x.html">attr_get(3x)</A></STRONG> for soft- - label key lines, and <STRONG><A HREF="curs_slk.3x.html">extended_slk_color(3x)</A></STRONG> as a form of <STRONG><A HREF="curs_slk.3x.html">slk_color(3x)</A></STRONG> - that can gather color information from them when many colors are + <EM>ncurses</EM> offers <STRONG><A HREF="curs_slk.3x.html">slk_attr(3x)</A></STRONG> as a counterpart of <STRONG><A HREF="curs_attr.3x.html">attr_get(3x)</A></STRONG> for soft- + label key lines, and <STRONG><A HREF="curs_slk.3x.html">extended_slk_color(3x)</A></STRONG> as a form of <STRONG><A HREF="curs_slk.3x.html">slk_color(3x)</A></STRONG> + that can gather color information from them when many colors are supported. - Some extensions are available only if <EM>ncurses</EM> permits modification of - <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>'s behavior; see <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG>. <EM>ncurses</EM> is compiled - to support them; section "ALTERNATE CONFIGURATIONS" describes how. + <EM>ncurses</EM> permits modification of <STRONG><A HREF="unctrl.3x.html">unctrl(3x)</A></STRONG>'s behavior; see + <STRONG><A HREF="legacy_coding.3x.html">use_legacy_coding(3x)</A></STRONG>. - <STRONG>o</STRONG> Rudimentary support for multi-threaded applications may be - available; see <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>. + Rudimentary support for multi-threaded applications may be available; + see <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>. - <STRONG>o</STRONG> Functions that ease the management of multiple screens can be - exposed; see <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>. + Functions that ease the management of multiple screens can be exposed; + see <STRONG><A HREF="curs_sp_funcs.3x.html">curs_sp_funcs(3x)</A></STRONG>. - <STRONG>o</STRONG> To aid applications to debug their memory usage, <EM>ncurses</EM> optionally - offers functions to more aggressively free memory it dynamically - allocates itself; see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>. + To aid applications to debug their memory usage, <EM>ncurses</EM> optionally + offers functions to more aggressively free memory it dynamically + allocates itself; see <STRONG><A HREF="curs_memleaks.3x.html">curs_memleaks(3x)</A></STRONG>. - <STRONG>o</STRONG> The library facilitates auditing and troubleshooting of its - behavior; see <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>. + The library facilitates auditing and troubleshooting of its behavior; + see <STRONG><A HREF="curs_trace.3x.html">curs_trace(3x)</A></STRONG>. - <STRONG>o</STRONG> The compiler option <STRONG>-DUSE_GETCAP</STRONG> causes the library to fall back to - reading <EM>/etc/termcap</EM> if the terminal setup code cannot find a <EM>term-</EM> - <EM>info</EM> entry corresponding to <EM>TERM</EM>. Use of this feature is not - recommended, as it essentially includes an entire <EM>termcap</EM> compiler - in the <EM>ncurses</EM> startup code, at a cost in memory usage and - application launch latency. + Compiling <EM>ncurses</EM> with the option <STRONG>-DUSE_GETCAP</STRONG> causes it to fall back + to reading <EM>/etc/termcap</EM> if the terminal setup code cannot find a <EM>term-</EM> + <EM>info</EM> entry corresponding to <EM>TERM</EM>. Use of this feature is not + recommended, as it essentially includes an entire <EM>termcap</EM> compiler in + the <EM>ncurses</EM> startup code, at a cost in memory usage and application + launch latency. <EM>PDCurses</EM> and NetBSD <EM>curses</EM> incorporate some <EM>ncurses</EM> extensions. Individual man pages indicate where this is the case. @@ -1343,7 +1377,7 @@ The latter includes several additional features, such as wide-character and color support. <EM>ncurses</EM> intends base-level conformance with X/Open Curses, and supports all features of its enhanced level except the - <STRONG>untic</STRONG> utility. + <EM>untic</EM> utility. Differences between X/Open Curses and <EM>ncurses</EM> are documented in the "PORTABILITY" sections of applicable man pages. @@ -1357,14 +1391,14 @@ as those to <EM>WINDOW</EM> structures, to ensure that they are not null. This is done primarily to guard against programmer error. The standard interface does not provide a way for the library to tell an application - which of several possible errors occurred. Relying on this (or some - other) extension adversely affects the portability of <EM>curses</EM> - applications. + which of several possible errors occurred. An application that relies + on <EM>ncurses</EM> to check its function parameters for validity limits its + portability and robustness. </PRE><H3><a name="h3-Padding-Differences">Padding Differences</a></H3><PRE> - In historical <EM>curses</EM> implementations, delays embedded in the <EM>terminfo</EM> - capabilities <STRONG>carriage_return</STRONG> (<STRONG>cr</STRONG>), <STRONG>scroll_forward</STRONG> (<STRONG>ind</STRONG>), <STRONG>cursor_left</STRONG> + In historical <EM>curses</EM> implementations, delays embedded in the <EM>terminfo</EM> + capabilities <STRONG>carriage_return</STRONG> (<STRONG>cr</STRONG>), <STRONG>scroll_forward</STRONG> (<STRONG>ind</STRONG>), <STRONG>cursor_left</STRONG> (<STRONG>cub1</STRONG>), <STRONG>form_feed</STRONG> (<STRONG>ff</STRONG>), and <STRONG>tab</STRONG> (<STRONG>ht</STRONG>) activated corresponding delay bits in the Unix terminal driver. <EM>ncurses</EM> performs all padding by sending NUL bytes to the device. This method is slightly more expensive, but @@ -1383,65 +1417,62 @@ but does not finish the story. A more complete account follows. - <STRONG>o</STRONG> Starting with 4BSD <EM>curses</EM> (1980) all implementations have provided - a <EM>curses.h</EM> file. + <STRONG>o</STRONG> The first <EM>curses</EM>, in 4BSD, provided a <EM>curses.h</EM> file. - BSD <EM>curses</EM> code included <EM>curses.h</EM> and <EM>unctrl.h</EM> from an internal + BSD <EM>curses</EM> code included <EM>curses.h</EM> and <EM>unctrl.h</EM> from an internal header file <EM>curses.ext</EM>, where "ext" abbreviated "externs". - The implementations of <EM>printw</EM> and <EM>scanw</EM> used undocumented internal - functions of the standard I/O library (<STRONG>_</STRONG><EM>doprnt</EM> and <STRONG>_</STRONG><EM>doscan</EM>), but + The implementations of <EM>printw</EM> and <EM>scanw</EM> used undocumented internal + functions of the standard I/O library (<STRONG>_</STRONG><EM>doprnt</EM> and <STRONG>_</STRONG><EM>doscan</EM>), but nothing in <EM>curses.h</EM> itself relied upon <EM>stdio.h</EM>. - <STRONG>o</STRONG> SVr2 <EM>curses</EM> added <EM>newterm</EM>, which relies upon <EM>stdio.h</EM> because its + <STRONG>o</STRONG> SVr2 <EM>curses</EM> added <EM>newterm</EM>, which relies upon <EM>stdio.h</EM> because its function prototype employs the <EM>FILE</EM> type. SVr4 <EM>curses</EM> added <EM>putwin</EM> and <EM>getwin</EM>, which also use <EM>stdio.h</EM>. X/Open Curses specifies all three of these functions. - SVr4 <EM>curses</EM> and X/Open Curses do not require the developer to - include <EM>stdio.h</EM> before <EM>curses.h</EM>. Both document use of <EM>curses</EM> as + SVr4 <EM>curses</EM> and X/Open Curses do not require the developer to + include <EM>stdio.h</EM> before <EM>curses.h</EM>. Both document use of <EM>curses</EM> as requiring only <EM>curses.h</EM>. As a result, standard <EM>curses.h</EM> always includes <EM>stdio.h</EM>. - <STRONG>o</STRONG> X/Open Curses and SVr4 <EM>curses</EM> are inconsistent with respect to + <STRONG>o</STRONG> X/Open Curses and SVr4 <EM>curses</EM> are inconsistent with respect to <EM>unctrl.h</EM>. - As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, <EM>ncurses</EM> includes <EM>unctrl.h</EM> from <EM>curses.h</EM> + As noted in <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG>, <EM>ncurses</EM> includes <EM>unctrl.h</EM> from <EM>curses.h</EM> (as SVr4 does). - <STRONG>o</STRONG> X/Open Curses's comments about <EM>term.h</EM> and <EM>termios.h</EM> may refer to + <STRONG>o</STRONG> X/Open Curses's comments about <EM>term.h</EM> and <EM>termios.h</EM> may refer to HP-UX and AIX. - HP-UX <EM>curses</EM> includes <EM>term.h</EM> from <EM>curses.h</EM> to declare <EM>setupterm</EM> in + HP-UX <EM>curses</EM> includes <EM>term.h</EM> from <EM>curses.h</EM> to declare <EM>setupterm</EM> in <EM>curses.h</EM>, but <EM>ncurses</EM> and Solaris <EM>curses</EM> do not. - AIX <EM>curses</EM> includes <EM>term.h</EM> and termios.h<EM>.</EM> Again, <EM>ncurses</EM> and + AIX <EM>curses</EM> includes <EM>term.h</EM> and <EM>termios.h</EM>. Again, <EM>ncurses</EM> and Solaris <EM>curses</EM> do not. - <STRONG>o</STRONG> X/Open Curses says that <EM>curses.h</EM> <STRONG>may</STRONG> include <EM>term.h</EM>, but does not + <STRONG>o</STRONG> X/Open Curses says that <EM>curses.h</EM> <STRONG>may</STRONG> include <EM>term.h</EM>, but does not require it to do so. - Some programs use functions declared in both <EM>curses.h</EM> and <EM>term.h</EM>, - and must include both header files in the same module. Very old - versions of AIX <EM>curses</EM> required inclusion of <EM>curses.h</EM> before - <EM>term.h</EM>. + Some programs use functions declared in both <EM>curses.h</EM> and <EM>term.h</EM>, + and must include both header files in the same translation unit. - The header files supplied by <EM>ncurses</EM> include the standard library - headers required for its declarations, so <EM>ncurses</EM>'s own header - files can be included in any order. But for portability, you - should include <EM>curses.h</EM> before <EM>term.h</EM>. + The header files supplied by <EM>ncurses</EM> include the standard library + headers required for its declarations, so <EM>ncurses</EM>'s own header + files can be included in any order. For portability even to old + AIX systems, include <EM>curses.h</EM> before <EM>term.h</EM>. - <STRONG>o</STRONG> X/Open Curses says "may make visible" because including a header - file does not necessarily make visible all of the symbols in it + <STRONG>o</STRONG> X/Open Curses says "may make visible" because including a header + file does not necessarily make visible all of the symbols in it (consider <STRONG>#ifdef</STRONG> and similar). - For instance, <EM>ncurses</EM>'s <EM>curses.h</EM> <STRONG>may</STRONG> include <EM>wchar.h</EM> if the proper - symbol is defined, and if <EM>ncurses</EM> is configured for wide-character - support. If <EM>wchar.h</EM> is included, its symbols <STRONG>may</STRONG> be made visible - depending on the value of the <STRONG>_XOPEN_SOURCE</STRONG> feature test macro. + For instance, <EM>ncurses</EM>'s <EM>curses.h</EM> <STRONG>may</STRONG> include <EM>wchar.h</EM> if the proper + symbol is defined, and if <EM>ncurses</EM> is configured for wide-character + support. If <EM>wchar.h</EM> is included, its symbols <STRONG>may</STRONG> be made visible + depending on the value of the <STRONG>_</STRONG><EM>XOPEN</EM><STRONG>_</STRONG><EM>SOURCE</EM> feature test macro. <STRONG>o</STRONG> X/Open Curses mandates an application's inclusion of one standard C library header in a special case: <EM>stdarg.h</EM> before <EM>curses.h</EM> to @@ -1462,7 +1493,7 @@ No conforming implementations of X/Open Curses require an application to include <EM>stdarg.h</EM> before <EM>curses.h</EM> because they either - have allowed for a special type, or, like <EM>ncurses</EM>, they include + have allowed for a special type, or, like <EM>ncurses</EM>, they include <EM>stdarg.h</EM> themselves to provide a portable interface. @@ -1474,9 +1505,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> - - -ncurses 6.5 2024-04-27 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/ncursesw6-config.1.html b/doc/html/man/ncursesw6-config.1.html index 6380a6dda3b7..b340e73040f2 100644 --- a/doc/html/man/ncursesw6-config.1.html +++ b/doc/html/man/ncursesw6-config.1.html @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: MKncu_config.in,v 1.24 2024/04/20 21:13:38 tom Exp @ + * @Id: MKncu_config.in,v 1.25 2024/05/11 20:39:53 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>ncursesw6-config 1 2024-04-20 ncurses 6.5 User commands</TITLE> +<TITLE>ncursesw6\-config 1 2024-05-11 ncurses 6.6 User commands</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">ncursesw6-config 1 2024-04-20 ncurses 6.5 User commands</H1> +<H1 class="no-header">ncursesw6\-config 1 2024-05-11 ncurses 6.6 User commands</H1> <PRE> <STRONG><A HREF="ncursesw6-config.1.html">ncursesw6-config(1)</A></STRONG> User commands <STRONG><A HREF="ncursesw6-config.1.html">ncursesw6-config(1)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>ncursesw6-config</STRONG> - configuration helper for <EM>ncurses</EM> libraries @@ -96,7 +94,7 @@ <EM>/usr/share/terminfo</EM>. <STRONG>--termpath</STRONG> reports the <EM>TERMPATH</EM> supplemental search path for the - <EM>termcap</EM> database, if support for <EM>termcap</EM> is + <EM>termcap</EM> database, if support for <EM>termcap</EM> is configured. The following options cause all others to be ignored. @@ -110,9 +108,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="ncursesw6-config.1.html">ncursesw6-config(1)</A></STRONG> +ncurses 6.6 2024-05-11 <STRONG><A HREF="ncursesw6-config.1.html">ncursesw6-config(1)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/new_pair.3x.html b/doc/html/man/new_pair.3x.html index 3cc73d6f3e29..feabc87016e6 100644 --- a/doc/html/man/new_pair.3x.html +++ b/doc/html/man/new_pair.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * authorization. * **************************************************************************** * Author: Thomas E. Dickey - * @Id: new_pair.3x,v 1.46 2024/03/16 15:35:01 tom Exp @ + * @Id: new_pair.3x,v 1.51 2025/08/16 19:11:47 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>new_pair 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>new_pair 3x 2025-08-16 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">new_pair 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">new_pair 3x 2025-08-16 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG> Library calls <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>alloc_pair</STRONG>, <STRONG>find_pair</STRONG>, <STRONG>free_pair</STRONG> - dynamically allocate <EM>curses</EM> color pairs @@ -62,16 +60,16 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> These functions are an extension to the <EM>curses</EM> library. They permit an - application to dynamically allocate a color pair using the - foreground/background colors rather than assign a fixed color pair + application to dynamically allocate a color pair using the + foreground/background colors rather than assign a fixed color pair number, and return an unused pair to the pool. - The number of colors may be related to the number of possible color + The number of colors may be related to the number of possible color pairs for a given terminal, or it may not: - <STRONG>o</STRONG> While almost all terminals allow setting the color <EM>attributes</EM> - independently, it is unlikely that your terminal allows you to - modify the attributes of a given character cell without rewriting + <STRONG>o</STRONG> While almost all terminals allow setting the color <EM>attributes</EM> + independently, it is unlikely that your terminal allows you to + modify the attributes of a given character cell without rewriting it. That is, the foreground and background colors are applied as a pair. @@ -91,10 +89,10 @@ <EM>(</EM> <STRONG>COLORS</STRONG> <EM>+</EM> <EM>1</EM> <EM>)</EM> <EM>*</EM> <EM>(</EM> <STRONG>COLORS</STRONG> <EM>+</EM> <EM>1</EM> <EM>)</EM> <STRONG>o</STRONG> An application might use up to a few dozen color pairs to implement - a predefined color scheme. + a color scheme. - Beyond that lies in the realm of programs using the foreground and - background colors for "ASCII art" (or some other non-textual + Beyond that lies in the realm of programs using the foreground and + background colors for "ASCII art" (or some other non-textual application). Also beyond those few dozen pairs, the required size for a table to @@ -107,7 +105,7 @@ </PRE><H3><a name="h3-alloc_pair">alloc_pair</a></H3><PRE> The <STRONG>alloc_pair</STRONG> function accepts parameters for foreground and - background color, and checks if that color combination is already + background color, and checks whether that color combination is already associated with a color pair. <STRONG>o</STRONG> If the combination already exists, <STRONG>alloc_pair</STRONG> returns the existing @@ -116,20 +114,20 @@ <STRONG>o</STRONG> If the combination does not exist, <STRONG>alloc_pair</STRONG> allocates a new color pair and returns that. - <STRONG>o</STRONG> If the table fills up, <STRONG>alloc_pair</STRONG> discards the least-recently + <STRONG>o</STRONG> If the table fills up, <STRONG>alloc_pair</STRONG> discards the least-recently allocated entry using <STRONG>free_pair</STRONG> and allocates a new color pair. - All of the color pairs are allocated from a table of possible color - pairs. The size of the table is determined by the terminfo <STRONG>pairs</STRONG> - capability. The table is shared with <STRONG>init_pair</STRONG>; in fact <STRONG>alloc_pair</STRONG> - calls <STRONG>init_pair</STRONG> after updating the <EM>ncurses</EM> library's fast index to the + All of the color pairs are allocated from a table of possible color + pairs. The size of the table is determined by the terminfo <STRONG>pairs</STRONG> + capability. The table is shared with <STRONG>init_pair</STRONG>; in fact <STRONG>alloc_pair</STRONG> + calls <STRONG>init_pair</STRONG> after updating the <EM>ncurses</EM> library's fast index to the colors versus color pairs. </PRE><H3><a name="h3-find_pair">find_pair</a></H3><PRE> The <STRONG>find_pair</STRONG> function accepts parameters for foreground and background - color, and checks if that color combination is already associated with - a color pair, returning the pair number if it has been allocated. + color, and checks whether that color combination is already associated + with a color pair, returning the pair number if it has been allocated. Otherwise it returns -1. @@ -163,9 +161,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG> +ncurses 6.6 2025-08-16 <STRONG><A HREF="new_pair.3x.html">new_pair(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/panel.3x.html b/doc/html/man/panel.3x.html index 58ad42d26efe..71bcce9eb358 100644 --- a/doc/html/man/panel.3x.html +++ b/doc/html/man/panel.3x.html @@ -27,27 +27,25 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: panel.3x,v 1.63 2024/03/16 15:35:01 tom Exp @ + * @Id: panel.3x,v 1.68 2024/12/28 21:26:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>panel 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>panel 3x 2024-12-28 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">panel 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">panel 3x 2024-12-28 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG> Library calls <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> - panel - panel stack extension for <EM>curses</EM> + panel - manage overlapping <EM>curses</EM> windows </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> @@ -141,7 +139,7 @@ </PRE><H3><a name="h3-panel_below">panel_below</a></H3><PRE> <STRONG>panel_below(</STRONG><EM>pan</EM><STRONG>)</STRONG> returns a pointer to the panel just below <EM>pan</EM>. If the - panel argument is "<STRONG>(PANEL</STRONG> <STRONG>*)0</STRONG>", it returns a pointer to the top panel + panel argument is "<STRONG>(PANEL</STRONG> <STRONG>*)0</STRONG>", it returns a pointer to the top panel in the stack. @@ -172,7 +170,7 @@ </PRE><H3><a name="h3-show_panel">show_panel</a></H3><PRE> - <STRONG>show_panel(</STRONG><EM>pan</EM><STRONG>)</STRONG> makes a hidden panel visible by placing it on top of + <STRONG>show_panel(</STRONG><EM>pan</EM><STRONG>)</STRONG> makes a hidden panel visible by placing it on top of the panels in the panel stack. See "PORTABILITY" below. @@ -187,21 +185,21 @@ refresh the physical screen. Use this function and not <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG> or <STRONG><A HREF="curs_refresh.3x.html">wnoutrefresh(3x)</A></STRONG>. - <STRONG>update_panels</STRONG> may be called more than once before a call to <STRONG>doupdate</STRONG>, - but <STRONG>doupdate</STRONG> is the function responsible for updating the physical + <STRONG>update_panels</STRONG> may be called more than once before a call to <STRONG>doupdate</STRONG>, + but <STRONG>doupdate</STRONG> is the function responsible for updating the physical screen. </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - Each routine that returns a pointer returns <STRONG>NULL</STRONG> if an error occurs. - Each routine that returns an int value returns <STRONG>OK</STRONG> if it executes + Each routine that returns a pointer returns <EM>NULL</EM> if an error occurs. + Each routine that returns an int value returns <STRONG>OK</STRONG> if it executes successfully and <STRONG>ERR</STRONG> if not. - Except as noted, the <EM>pan</EM> and <EM>window</EM> parameters must be non-null. If + Except as noted, the <EM>pan</EM> and <EM>window</EM> parameters must be non-null. If either is null, an error is returned. - The <STRONG>move_panel</STRONG> function uses <STRONG><A HREF="curs_window.3x.html">mvwin(3x)</A></STRONG>, and returns an error if <STRONG>mvwin</STRONG> - returns an error. + The <STRONG>move_panel</STRONG> function uses <STRONG><A HREF="curs_window.3x.html">mvwin(3x)</A></STRONG>, and returns <STRONG>ERR</STRONG> if <STRONG>mvwin</STRONG> + returns <STRONG>ERR</STRONG>. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> @@ -209,8 +207,8 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - Reasonable care has been taken to ensure compatibility with the native - panel facility introduced in System V; inspection of the SVr4 manual + Reasonable care has been taken to ensure compatibility with the native + panel facility introduced in System V; inspection of the SVr4 manual pages suggests the programming interface never changed. The <EM>PANEL</EM> data structures are merely similar. The programmer is cautioned not to directly use <EM>PANEL</EM> fields. @@ -236,24 +234,24 @@ library. <STRONG>o</STRONG> <EM>ncurses</EM> (since version 0.6 in 1993) and <EM>PDCurses</EM> (since version 2.2 - in 1995) provide a panel library whose common ancestor is a public - domain implementation by Warren Tucker published in <EM>u386mon</EM> 2.20 + in 1995) provide a <EM>panel</EM> library whose common ancestor is a public + domain implementation by Warren Tucker published in <EM>u386mon</EM> 2.20 (1990). - According to Tucker, the System V panel library was first released - in SVr3.2 (1988), and his implementation helped with a port to + According to Tucker, the System V panel library was first released + in SVr3.2 (1988), and his implementation helped with a port to SVr3.1 (1987). - Several developers have improved each of these; they are no longer + Several developers have improved each of these; they are no longer the same as Tucker's implementation. - <STRONG>o</STRONG> NetBSD 8 (2018) has a panel library begun by Valery Ushakov in + <STRONG>o</STRONG> NetBSD 8 (2018) has a panel library begun by Valery Ushakov in 2015, based on the System V documentation. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> Warren Tucker <wht@n4hgf.mt-park.ga.us> originally wrote this - implementation, primarily to assist in porting <EM>u386mon</EM> to systems + implementation, primarily to assist in porting <EM>u386mon</EM> to systems without a native panel library. Zeyd ben-Halim repackaged it for <EM>ncurses</EM>. @@ -264,9 +262,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG> +ncurses 6.6 2024-12-28 <STRONG><A HREF="panel.3x.html">panel(3x)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/resizeterm.3x.html b/doc/html/man/resizeterm.3x.html index 23491462792c..b0c01596b179 100644 --- a/doc/html/man/resizeterm.3x.html +++ b/doc/html/man/resizeterm.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * authorization. * **************************************************************************** * Author: Thomas E. Dickey 1996-on - * @Id: resizeterm.3x,v 1.56 2024/03/16 15:35:01 tom Exp @ + * @Id: resizeterm.3x,v 1.65 2025/07/05 13:06:45 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>resizeterm 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>resizeterm 3x 2025-07-05 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">resizeterm 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">resizeterm 3x 2025-07-05 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> Library calls <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>is_term_resized</STRONG>, <STRONG>resize_term</STRONG>, <STRONG>resizeterm</STRONG> - manage the terminal dimensions understood by <EM>curses</EM> @@ -62,21 +60,21 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> This is an extension to the <EM>curses</EM> library. It provides callers with a - hook into the <EM>ncurses</EM> data to resize windows, primarily for use by - programs running in an X Window terminal (e.g., xterm) when the + hook into the <EM>ncurses</EM> data to resize windows, primarily for use by + programs running in an X Window terminal (e.g., xterm) when the terminal's screen size is changed by the user: - <STRONG>o</STRONG> <EM>curses</EM> windows cannot extend outside the screen. If the terminal + <STRONG>o</STRONG> <EM>curses</EM> windows cannot extend outside the screen. If the terminal is shrunk, <EM>curses</EM> windows must be shrunk to fit. - <STRONG>o</STRONG> If the terminal is stretched, rows and/or columns can be added to + <STRONG>o</STRONG> If the terminal is stretched, rows and/or columns can be added to existing windows. The added cells should match the current attributes of the windows. - If the calling program has not set up a handler for <STRONG>SIGWINCH</STRONG> when it - initializes <EM>ncurses</EM> (e.g., using <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>), then - <EM>ncurses</EM> sets a handler for <STRONG>SIGWINCH</STRONG> which notifies the library when a - window-size event has occurred. The library checks for this + If the application has not set up a handler for <EM>SIGWINCH</EM> when it + initializes <EM>ncurses</EM> (by calling <STRONG><A HREF="curs_initscr.3x.html">initscr(3x)</A></STRONG> or <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG>), then + <EM>ncurses</EM> establishes a <EM>SIGWINCH</EM> handler that notifies the library when a + window-resizing event has occurred. The library checks for this notification <STRONG>o</STRONG> when reading input data, @@ -89,36 +87,34 @@ When the library has found that the terminal's window-size has changed, it calls <STRONG>resizeterm</STRONG> to update its data structures. - An application which establishes its own <STRONG>SIGWINCH</STRONG> handler can call - <STRONG>resizeterm</STRONG>, but in that case, the library will not see <STRONG>SIGWINCH</STRONG>, and + An application which establishes its own <EM>SIGWINCH</EM> handler can call + <STRONG>resizeterm</STRONG>, but in that case, the library will not see <EM>SIGWINCH</EM>, and proper layout will rely upon the application. -</PRE><H2><a name="h2-FUNCTIONS">FUNCTIONS</a></H2><PRE> - </PRE><H3><a name="h3-resizeterm">resizeterm</a></H3><PRE> The function <STRONG>resizeterm</STRONG> resizes the standard and current windows (i.e., - <STRONG>stdscr</STRONG> and <STRONG>curscr</STRONG>) to the specified dimensions, and adjusts other - bookkeeping data used by the <EM>ncurses</EM> library that record the window + <STRONG>stdscr</STRONG> and <STRONG>curscr</STRONG>) to the specified dimensions, and adjusts other + bookkeeping data used by the <EM>ncurses</EM> library that record the window dimensions such as the <STRONG>LINES</STRONG> and <STRONG>COLS</STRONG> variables. </PRE><H3><a name="h3-resize_term">resize_term</a></H3><PRE> - Most of the work for <STRONG>resizeterm</STRONG> is done by the inner function - <STRONG>resize_term</STRONG>. The outer function <STRONG>resizeterm</STRONG> adds bookkeeping for the - <STRONG>SIGWINCH</STRONG> handler, as well as repainting the soft-key area (see + Most of the work for <STRONG>resizeterm</STRONG> is done by the inner function + <STRONG>resize_term</STRONG>. The outer function <STRONG>resizeterm</STRONG> adds bookkeeping for the + <EM>SIGWINCH</EM> handler, as well as repainting the soft-key area (see <STRONG><A HREF="curs_slk.3x.html">slk_touch(3x)</A></STRONG>). - The <STRONG>resize_term</STRONG> function attempts to resize all windows. This helps + The <STRONG>resize_term</STRONG> function attempts to resize all windows. This helps with simple applications. However: <STRONG>o</STRONG> It is not possible to automatically resize pads. <STRONG>o</STRONG> Applications which have complicated layouts should check for - <STRONG>KEY_RESIZE</STRONG> returned from <STRONG>wgetch</STRONG>, and adjust their layout, e.g., + <STRONG>KEY_RESIZE</STRONG> returned from <STRONG>wgetch</STRONG>, and adjust their layout, e.g., using <STRONG>wresize</STRONG> and <STRONG>mvwin</STRONG>, or by recreating the windows. - When resizing windows, <STRONG>resize_term</STRONG> recursively adjusts subwindows, + When resizing windows, <STRONG>resize_term</STRONG> recursively adjusts subwindows, keeping them within the updated parent window's limits. If a top-level window happens to extend to the screen's limits, then on resizing the window, <STRONG>resize_term</STRONG> will keep the window extending to the corresponding @@ -134,19 +130,19 @@ </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> Except as noted, these functions return the integer <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success. They will fail if either of the dimensions are less - than or equal to zero, or if an error occurs while (re)allocating + than or equal to zero, or if an error occurs while (re)allocating memory for the windows. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - While these functions are intended to be used to support a signal - handler (i.e., for <STRONG>SIGWINCH</STRONG>), care should be taken to avoid invoking - them in a context where <STRONG>malloc</STRONG> or <STRONG>realloc</STRONG> may have been interrupted, + While these functions are intended to be used to support a signal + handler (i.e., for <EM>SIGWINCH</EM>), care should be taken to avoid invoking + them in a context where <STRONG>malloc</STRONG> or <STRONG>realloc</STRONG> may have been interrupted, since it uses those functions. - If <EM>ncurses</EM> is configured to supply its own <STRONG>SIGWINCH</STRONG> handler, + If <EM>ncurses</EM> is configured to supply its own <EM>SIGWINCH</EM> handler, - <STRONG>o</STRONG> on receipt of a <STRONG>SIGWINCH</STRONG>, the handler sets a flag + <STRONG>o</STRONG> on receipt of a <EM>SIGWINCH</EM>, the handler sets a flag <STRONG>o</STRONG> which is tested in <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">doupdate(3x)</A></STRONG> and <STRONG><A HREF="curs_terminfo.3x.html">restartterm(3x)</A></STRONG>, @@ -160,12 +156,12 @@ that cannot be done automatically. Calling <STRONG>resizeterm</STRONG> or <STRONG>resize_term</STRONG> directly from a signal handler is - unsafe. This indirect method is used to provide a safe way to + unsafe. This indirect method is used to provide a safe way to resize the <EM>ncurses</EM> data structures. - If the environment variables <EM>LINES</EM> or <EM>COLUMNS</EM> are set, this overrides - the library's use of the window size obtained from the operating - system. Thus, even if a <STRONG>SIGWINCH</STRONG> is received, no screen size change + If the environment variables <EM>LINES</EM> or <EM>COLUMNS</EM> are set, this overrides + the library's use of the window size obtained from the operating + system. Thus, even if a <EM>SIGWINCH</EM> is received, no screen size change may be recorded. @@ -178,28 +174,25 @@ Doing that clears the screen and is visually distracting. - This extension of <EM>ncurses</EM> was introduced in mid-1995. It was adopted - in NetBSD <EM>curses</EM> (2001) and PDCurses (2003). + <EM>ncurses</EM> introduced this extension in mid-1995. NetBSD <EM>curses</EM> adopted + it in 2001 and <EM>PDCurses</EM> in 2003. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> - Thomas Dickey (from an equivalent function written in 1988 for BSD + Thomas Dickey (from an equivalent function written in 1988 for BSD <EM>curses</EM>) </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="curs_getch.3x.html">curs_getch(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> +ncurses 6.6 2025-07-05 <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> </PRE> <div class="nav"> <ul> <li><a href="#h2-NAME">NAME</a></li> <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> -<li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> -<li><a href="#h2-FUNCTIONS">FUNCTIONS</a> +<li><a href="#h2-DESCRIPTION">DESCRIPTION</a> <ul> <li><a href="#h3-resizeterm">resizeterm</a></li> <li><a href="#h3-resize_term">resize_term</a></li> diff --git a/doc/html/man/scr_dump.5.html b/doc/html/man/scr_dump.5.html index a96342558ecb..55785fe3569b 100644 --- a/doc/html/man/scr_dump.5.html +++ b/doc/html/man/scr_dump.5.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: scr_dump.5,v 1.46 2024/03/23 20:42:29 tom Exp @ + * @Id: scr_dump.5,v 1.52 2025/04/05 21:56:26 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>scr_dump 5 2024-03-23 ncurses 6.5 File formats</TITLE> +<TITLE>scr_dump 5 2025-04-05 ncurses 6.6 File formats</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">scr_dump 5 2024-03-23 ncurses 6.5 File formats</H1> +<H1 class="no-header">scr_dump 5 2025-04-05 ncurses 6.6 File formats</H1> <PRE> <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG> File formats <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> scr_dump - <EM>curses</EM> screen dump @@ -108,7 +106,7 @@ </PRE><H3><a name="h3-ncurses5-_Legacy_">ncurses5 (Legacy)</a></H3><PRE> The screen-dump feature was added to <EM>ncurses</EM> in June 1995. While there - were fixes and improvements in succeeding years, the basic scheme was + were fixes and improvements in succeeding years, the basic scheme was unchanged: <STRONG>o</STRONG> The <EM>WINDOW</EM> structure was written in binary form. @@ -130,18 +128,18 @@ </PRE><H3><a name="h3-X_Open-Curses">X/Open Curses</a></H3><PRE> - X/Open Curses, Issue 7 specifies little. It says (boldface emphasis + X/Open Curses Issue 7 specifies little. It says (boldface emphasis added) - "[t]he <EM>getwin()</EM> function reads window-related data stored in the - file by <EM>putwin()</EM>. The function then creates and initializes a new + "[t]he <EM>getwin()</EM> function reads window-related data stored in the + file by <EM>putwin()</EM>. The function then creates and initializes a new window using that data. - The <EM>putwin()</EM> function writes all data associated with <EM>win</EM> into the - <EM>stdio</EM> stream to which <EM>filep</EM> points, using an <STRONG>unspecified</STRONG> <STRONG>format</STRONG>. + The <EM>putwin()</EM> function writes all data associated with <EM>win</EM> into the + <EM>stdio</EM> stream to which <EM>filep</EM> points, using an <STRONG>unspecified</STRONG> <STRONG>format</STRONG>. This information can be retrieved later using <EM>getwin()</EM>." - In the mid-1990s when the X/Open Curses document was written, there + In the mid-1990s when the X/Open Curses document was written, there were still System V systems using older, less capable <EM>curses</EM> libraries. BSD <EM>curses</EM> was not relevant to X/Open because it did not meet the criteria for base-level conformance; see <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. @@ -162,14 +160,14 @@ #define SVR3_DUMP_MAGIC_NUMBER 0434 That is, the feature was likely introduced in SVr2 (1984), and improved - in SVr3 (1987). Solaris <EM>curses</EM> has no magic number for SVr4 (1989). - Other System V operating systems (AIX and HP-UX) use a magic number + in SVr3 (1987). Solaris <EM>curses</EM> has no magic number for SVr4 (1989). + Other System V operating systems (AIX and HP-UX) use a magic number that would correspond to the following. /* curses screen dump magic number */ #define SVR4_DUMP_MAGIC_NUMBER 0435 - That octal number in bytes is 001, 035. Because most Unix vendors at + That octal number in bytes is 001, 035. Because most Unix vendors at the time used big-endian hardware, the magic number is written with the high-order byte first. @@ -182,7 +180,7 @@ Nor do they use an identical format, even with the System V family. The <EM>ncurses</EM> <EM>savescreen</EM> test program was used to collect information for - this manual page. It produced dumps of different size (all on 64-bit + this manual page. It produced dumps of different size (all on 64-bit hardware, on 40x80 screens): <STRONG>o</STRONG> AIX (51817 bytes) @@ -195,29 +193,29 @@ </PRE><H3><a name="h3-Solaris">Solaris</a></H3><PRE> - As noted above, Solaris <EM>curses</EM> has no magic number corresponding to + As noted above, Solaris <EM>curses</EM> has no magic number corresponding to SVr4 <EM>curses</EM>. This is odd, since Solaris was the first operating system to meet the SVr4 guidelines. Solaris furthermore supplies two versions of <EM>curses</EM>. <STRONG>o</STRONG> The default <EM>curses</EM> library uses the SVr3 magic number. - <STRONG>o</STRONG> An alternate <EM>curses</EM> library (which we term <EM>xcurses),</EM> available in + <STRONG>o</STRONG> An alternate <EM>curses</EM> library (which we term <EM>xcurses),</EM> available in <EM>/usr/xpg4</EM>, uses a textual format with no magic number. According to its copyright notice, this <EM>xcurses</EM> library was developed by MKS (Mortice Kern Systems) from 1990 to 1995. - Like ncurses6, it includes a header with parameters. Unlike - ncurses6, the contents of the window are written piecemeal, with - coordinates and attributes for each chunk of text rather than + Like ncurses6, it includes a header with parameters. Unlike + ncurses6, the contents of the window are written piecemeal, with + coordinates and attributes for each chunk of text rather than writing the whole window from top to bottom. </PRE><H3><a name="h3-PDCurses">PDCurses</a></H3><PRE> - <EM>PDCurses</EM> added support for screen dumps in version 2.7 (2005). Like - System V and ncurses5, it writes the <EM>WINDOW</EM> structure in binary, but - begins the file with its three-byte identifier "PDC", followed by a + <EM>PDCurses</EM> added support for screen dumps in version 2.7 (2005). Like + System V and ncurses5, it writes the <EM>WINDOW</EM> structure in binary, but + begins the file with its three-byte identifier "PDC", followed by a single-byte version number. "PDC\001" @@ -227,7 +225,7 @@ As of April 2017, NetBSD <EM>curses</EM> does not support <STRONG>scr_dump</STRONG> and <STRONG>scr_restore</STRONG> (or <STRONG>scr_init</STRONG>, <STRONG>scr_set</STRONG>), although it has <STRONG>putwin</STRONG> and <STRONG>getwin</STRONG>. - Like ncurses5, NetBSD <STRONG>putwin</STRONG> does not identify its dumps with a useful + Like ncurses5, NetBSD <STRONG>putwin</STRONG> does not identify its dumps with a useful magic number. It writes <STRONG>o</STRONG> the <EM>curses</EM> shared library major and minor versions as the first two @@ -300,13 +298,13 @@ <STRONG>o</STRONG> The actual color pair values are not written to the file. - <STRONG>o</STRONG> All characters are shown in printable form; spaces are "\s" to + <STRONG>o</STRONG> All characters are shown in printable form; spaces are "\s" to ensure they are not overlooked. - <STRONG>o</STRONG> Attributes are written in escaped curly braces, e.g., "\{BOLD}", + <STRONG>o</STRONG> Attributes are written in escaped curly braces, e.g., "\{BOLD}", and may include a color pair (C1 or C2 in this example). - <STRONG>o</STRONG> The parameters in the header are written out only if they are + <STRONG>o</STRONG> The parameters in the header are written out only if they are nonzero. When reading back, order does not matter. Running the same program with Solaris <EM>xpg4</EM> curses gives this dump: @@ -345,12 +343,12 @@ 9,19,0,0, CUR=11,5 - Solaris <STRONG>getwin</STRONG> requires that all parameters are present, and in the - same order. The <EM>xpg4</EM> curses library does not know about the <STRONG>bce</STRONG> (back + Solaris <STRONG>getwin</STRONG> requires that all parameters are present, and in the + same order. The <EM>xpg4</EM> curses library does not know about the <STRONG>bce</STRONG> (back color erase) capability, and does not color the window background. - On the other hand, the SVr4 curses library does know about the - background color. However, its screen dumps are in binary. Here is + On the other hand, the SVr4 curses library does know about the + background color. However, its screen dumps are in binary. Here is the corresponding dump (using "od -t x1"): 0000000 1c 01 c3 d6 f3 58 05 00 0b 00 0a 00 14 00 00 00 @@ -388,9 +386,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="curs_scr_dump.3x.html">curs_scr_dump(3x)</A></STRONG>, <STRONG><A HREF="curs_util.3x.html">curs_util(3x)</A></STRONG> - - -ncurses 6.5 2024-03-23 <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG> +ncurses 6.6 2025-04-05 <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/tabs.1.html b/doc/html/man/tabs.1.html index 5a548fab176b..dd2f6f288b9a 100644 --- a/doc/html/man/tabs.1.html +++ b/doc/html/man/tabs.1.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2008-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: tabs.1,v 1.59 2024/04/20 19:08:15 tom Exp @ + * @Id: tabs.1,v 1.74 2025/08/16 19:11:47 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>tabs 1 2024-04-20 ncurses 6.5 User commands</TITLE> +<TITLE>tabs 1 2025-08-16 ncurses 6.6 User commands</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">tabs 1 2024-04-20 ncurses 6.5 User commands</H1> +<H1 class="no-header">tabs 1 2025-08-16 ncurses 6.6 User commands</H1> <PRE> <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG> User commands <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>tabs</STRONG> - set terminal tab stops @@ -132,8 +130,8 @@ which is equivalent to the 1,6,11,16,21 example. -</PRE><H3><a name="h3-Predefined-Tab-Stops">Predefined Tab Stops</a></H3><PRE> - POSIX defines several predefined lists of tab stops. +</PRE><H3><a name="h3-Standard-Tab-Stops">Standard Tab Stops</a></H3><PRE> + POSIX defines several lists of tab stops. <STRONG>-a</STRONG> Assembler, IBM S/370, first format 1,10,16,36,72 @@ -180,7 +178,7 @@ on each line. The terminal's left margin is not modified. If the <EM>margin</EM> parameter is omitted, the default is 10. Use <STRONG>+m0</STRONG> to - reset the left margin, that is, to make it the left edge of the + reset the left margin, that is, to make it the left edge of the terminal's display. Before setting a left margin, <STRONG>tabs</STRONG> resets the margin to reduce problems that might arise from moving the cursor to the left of the current left margin. @@ -195,70 +193,67 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - IEEE Std 1003.1/The Open Group Base Specifications Issue 7 - (POSIX.1-2008) describes a <STRONG>tabs</STRONG> utility. However, + IEEE Std 1003.1/The Open Group Base Specifications Issue 7 + (POSIX.1-2008) describes a <EM>tabs</EM> utility. However, <STRONG>o</STRONG> this standard describes a <STRONG>+m</STRONG> option to set a terminal's left margin. Very few of the entries in the terminal database provide the <STRONG>set_left_margin</STRONG> (<STRONG>smgl</STRONG>) or <STRONG>set_left_margin_parm</STRONG> (<STRONG>smglp</STRONG>) capabilities needed to support the feature. - <STRONG>o</STRONG> There is no counterpart in X/Open Curses Issue 7 for this utility, - unlike <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG>. + <STRONG>o</STRONG> Unlike <EM>tput</EM>, <EM>tabs</EM> has no specification in X/Open Curses Issue 7. - The <STRONG>-d</STRONG> (debug) and <STRONG>-n</STRONG> (no-op) options are <EM>ncurses</EM> extensions not + The <STRONG>-d</STRONG> (debug) and <STRONG>-n</STRONG> (no-op) options are <EM>ncurses</EM> extensions not provided by other implementations. </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - A <STRONG>tabs</STRONG> utility appeared in PWB/Unix 1.0 (1977). A reduced version - shipped in Seventh Edition Unix (early 1979) and in 3BSD (later the - same year); it supported a "-n" option to set the first tab stop at the - left margin. That option is not specified by POSIX. - - The PWB/Unix <STRONG>tabs</STRONG> utility returned in System III (1980), and used - built-in tables to support a half-dozen hardcopy terminal (printer) - types. It also had logic to support setting the left margin, as well + A <EM>tabs</EM> utility appeared in PWB/Unix 1.0 (1977). A reduced version + shipped in Seventh Edition Unix (early 1979) and in 3BSD (later the + same year); it supported an option "-n" to set the first tab stop at + the left margin. That option is not specified by POSIX. + + The PWB/Unix <EM>tabs</EM> utility returned in System III (1980), and used + built-in tables to support a half-dozen hardcopy terminal (printer) + types. It also had logic to support setting the left margin, as well as a feature for copying the tab settings from a file. - Versions of the program in later releases of AT&T Unix, such as SVr4, - added support for the terminal database, but retained the tables to - support the printers. By this time, System V <STRONG>tput</STRONG> had incorporated the - tab stop initialization feature of BSD's <STRONG>tset</STRONG> from 1982, but employed + Versions of the program in later releases of AT&T Unix, such as SVr4, + added support for the terminal database, but retained the tables to + support the printers. By this time, System V <EM>tput</EM> had incorporated the + tab stop initialization feature of BSD's <EM>tset</EM> from 1982, but employed the <EM>terminfo</EM> database to do so. - The <STRONG>+m</STRONG> option was documented in the POSIX Base Specifications Issue 5 + The <STRONG>+m</STRONG> option was documented in the POSIX Base Specifications Issue 5 (Unix98, 1997), then omitted in Issue 6 (Unix03, 2004) without express motivation, though an introductory comment "and optionally adjusts the - margin" remains, overlooked in the removal. The <STRONG>tabs</STRONG> utility + margin" remains, overlooked in the removal. The <EM>tabs</EM> utility documented in Issues 6 and later has no mechanism for setting margins. - The <STRONG>+m</STRONG> option in <EM>ncurses</EM> <STRONG>tabs</STRONG> differs from the SVr4 feature by using - terminal capabilities rather than built-in tables. + The <STRONG>+m</STRONG> option in <EM>ncurses</EM>'s implementation differs from the SVr4 feature + by using terminal capabilities rather than built-in tables. - POSIX documents no limit on the number of tab stops. Other - implementations impose one; the limit is 20 in PWB/Unix's <STRONG>tabs</STRONG> utility. + POSIX documents no limit on the number of tab stops. Other + implementations impose one; the limit is 20 in PWB/Unix's <EM>tabs</EM> utility. While some terminals may not accept an arbitrary number of tab stops, - <EM>ncurses</EM> <STRONG>tabs</STRONG> attempts to set tab stops up to the right margin if the - list thereof is sufficiently long. + <EM>ncurses</EM> attempts to set tab stops up to the right margin if the list + thereof is sufficiently long. - The "Rationale" section of the Issue 6 <STRONG>tabs</STRONG> reference page details how - the committee considered redesigning the <STRONG>tabs</STRONG> and <STRONG>tput</STRONG> utilities, + The "Rationale" section of the Issue 6 <EM>tabs</EM> reference page details how + the committee considered redesigning the <EM>tabs</EM> and <EM>tput</EM> utilities, without settling on an improved solution. It claims that - "no known historical version of <EM>tabs</EM> supports the capability of - setting arbitrary tab stops." + no known historical version of <EM>tabs</EM> supports the capability of + setting arbitrary tab stops. The feature described in subsection "Explicit Lists" above was - implemented in PWB/Unix, and permitted the setting of abitrary tab + implemented in PWB/Unix, and permitted the setting of arbitrary tab stops nevertheless. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG> +ncurses 6.6 2025-08-16 <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -270,7 +265,7 @@ ncurses 6.5 2024-04-20 <STRONG>< <li><a href="#h3-General-Options">General Options</a></li> <li><a href="#h3-Implicit-Lists">Implicit Lists</a></li> <li><a href="#h3-Explicit-Lists">Explicit Lists</a></li> -<li><a href="#h3-Predefined-Tab-Stops">Predefined Tab Stops</a></li> +<li><a href="#h3-Standard-Tab-Stops">Standard Tab Stops</a></li> <li><a href="#h3-Margins">Margins</a></li> </ul> </li> diff --git a/doc/html/man/term.5.html b/doc/html/man/term.5.html index 9c9b5b8e52ac..b2675ae8d10c 100644 --- a/doc/html/man/term.5.html +++ b/doc/html/man/term.5.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,126 +28,124 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: term.5,v 1.77 2024/04/20 21:24:19 tom Exp @ + * @Id: term.5,v 1.85 2025/08/16 19:11:47 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>term 5 2024-04-20 ncurses 6.5 File formats</TITLE> +<TITLE>term 5 2025-08-16 ncurses 6.6 File formats</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">term 5 2024-04-20 ncurses 6.5 File formats</H1> +<H1 class="no-header">term 5 2025-08-16 ncurses 6.6 File formats</H1> <PRE> <STRONG><A HREF="term.5.html">term(5)</A></STRONG> File formats <STRONG><A HREF="term.5.html">term(5)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> term - compiled <EM>terminfo</EM> terminal description -</PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> - <STRONG>term</STRONG> - - </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> + <STRONG><A HREF="tic.1m.html">tic(1)</A></STRONG> compiles a <EM>terminfo</EM> terminal type description, and <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> + reads it. A compiled description may be stored in a file or in a + database of, potentially, many such descriptions. Further, a compiled + description may be in one of two formats: one similar to that used by + System V, and a newer, extensible format employed exclusively by + <EM>ncurses</EM>. + </PRE><H3><a name="h3-Storage-Location">Storage Location</a></H3><PRE> - Compiled terminfo descriptions are placed under the directory - <STRONG>/usr/share/terminfo</STRONG>. Two configurations are supported (when building - the <EM>ncurses</EM> libraries): + Compiled <EM>terminfo</EM> <EM>descriptions</EM> <EM>are</EM> <EM>placed</EM> under the directory + <EM>/usr/share/terminfo</EM>. One of two configurations is selected when + building the <EM>ncurses</EM> libraries. <STRONG>directory</STRONG> <STRONG>tree</STRONG> A two-level scheme is used to avoid a linear search of a huge Unix - system directory: <STRONG>/usr/share/terminfo/c/name</STRONG> where <EM>name</EM> is the + system directory: <EM>/usr/share/terminfo/</EM>c<EM>/</EM>name where <EM>name</EM> is the name of the terminal, and <EM>c</EM> is the first character of <EM>name</EM>. Thus, - <EM>act4</EM> can be found in the file <STRONG>/usr/share/terminfo/a/act4</STRONG>. - Synonyms for the same terminal are implemented by multiple links - to the same compiled file. + the compiled description of terminal type "act4" is found in the + file <EM>/usr/share/terminfo/a/act4</EM>. Synonyms for the same terminal + are implemented by multiple links to the same compiled file. <STRONG>hashed</STRONG> <STRONG>database</STRONG> - Using Berkeley database, two types of records are stored: the - terminfo data in the same format as stored in a directory tree - with the terminfo's primary name as a key, and records containing - only aliases pointing to the primary name. - - If built to write hashed databases, <EM>ncurses</EM> can still read - terminfo databases organized as a directory tree, but cannot write - entries into the directory tree. It can write (or rewrite) + Using the Berkeley database API, two types of records are stored: + the <EM>terminfo</EM> data in the same format as that stored in a directory + tree with the terminal's primary type name as a key, and records + containing only aliases pointing to the primary name. + + If built to write hashed databases, <EM>ncurses</EM> can still read <EM>term-</EM> + <EM>info</EM> databases organized as a directory tree, but cannot write + entries into the directory tree. It can write (or rewrite) entries in the hashed database. - <EM>ncurses</EM> distinguishes the two cases in the <EM>TERMINFO</EM> and - <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> environment variable by assuming a directory tree - for entries that correspond to an existing directory, and hashed + <EM>ncurses</EM> distinguishes the two cases in the <EM>TERMINFO</EM> and + <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> environment variable by assuming a directory tree + for entries that correspond to an existing directory, and a hashed database otherwise. </PRE><H3><a name="h3-Legacy-Storage-Format">Legacy Storage Format</a></H3><PRE> The format has been chosen so that it will be the same on all hardware. - An 8 or more bit byte is assumed, but no assumptions about byte - ordering or sign extension are made. + A byte of at least eight bits' width is assumed, but no assumptions + about bit ordering or sign extension are made. - The compiled file is created with the <STRONG>tic</STRONG> program, and read by the - routine <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>. The file is divided into six parts: + The file is divided into six parts: - a) <EM>header</EM>, + (a) <EM>header</EM>, - b) <EM>terminal</EM> <EM>names</EM>, + (b) <EM>terminal</EM> <EM>names</EM>, - c) <EM>Boolean</EM> <EM>flags</EM>, + (c) <EM>Boolean</EM> <EM>flags</EM>, - d) <EM>numbers</EM>, + (d) <EM>numbers</EM>, - e) <EM>strings</EM>, and + (e) <EM>strings</EM>, and - f) <EM>string</EM> <EM>table</EM>. + (f) a <EM>string</EM> <EM>table</EM>. The <EM>header</EM> section begins the file. This section contains six short integers in the format described below. These integers are - (1) the <EM>magic</EM> <EM>number</EM> (octal 0432); + (1) the <EM>magic</EM> <EM>number</EM> + (octal 0432); - (2) the size, in bytes, of the <EM>terminal</EM> <EM>names</EM> section; + (2) the size, + in bytes, of the <EM>terminal</EM> <EM>names</EM> section; (3) the number of bytes in the <EM>Boolean</EM> <EM>flags</EM> section; (4) the number of short integers in the <EM>numbers</EM> section; - (5) the number of offsets (short integers) in the <EM>strings</EM> section; + (5) the number of offsets + (short integers) in the <EM>strings</EM> section; - (6) the size, in bytes, of the <EM>string</EM> <EM>table</EM>. + (6) the size, + in bytes, of the <EM>string</EM> <EM>table</EM>. The capabilities in the <EM>Boolean</EM> <EM>flags</EM>, <EM>numbers</EM>, and <EM>strings</EM> sections - are in the same order as the file <term.h>. + are in the same order as in the header file <EM>term.h</EM>. - Short integers are signed, in the range -32768 to 32767. They are - stored as two 8-bit bytes. The first byte contains the least - significant 8 bits of the value, and the second byte contains the most - significant 8 bits. (Thus, the value represented is 256*second+first.) - This format corresponds to the hardware of the VAX and PDP-11 (that is, - little-endian machines). Machines where this does not correspond to - the hardware must read the integers as two bytes and compute the - little-endian value. + Short integers are signed, in the range -32768 to 32767, and stored in + little-endian format. Numbers in a terminal description, whether they are entries in the <EM>numbers</EM> or <EM>strings</EM> table, are positive integers. Boolean flags are treated as positive one-byte integers. In each case, those positive - integers represent a terminal capability. The terminal compiler tic + integers represent a terminal capability. The terminal compiler <EM>tic</EM> uses negative integers to handle the cases where a capability is not available: - <STRONG>o</STRONG> If a capability is absent from this terminal, tic stores a -1 in + <STRONG>o</STRONG> If a capability is absent from this terminal, <EM>tic</EM> stores a -1 in the corresponding table. The integer value -1 is represented by two bytes 0377, 0377. Absent Boolean values are represented by the byte 0 (false). - <STRONG>o</STRONG> If a capability has been canceled from this terminal, tic stores a + <STRONG>o</STRONG> If a capability has been canceled from this terminal, <EM>tic</EM> stores a -2 in the corresponding table. The integer value -2 is represented by two bytes 0377, 0376. @@ -156,7 +154,7 @@ <STRONG>o</STRONG> Other negative values are illegal. The <EM>terminal</EM> <EM>names</EM> section comes after the <EM>header</EM>. It contains the - first line of the terminfo description, listing the various names for + first line of the <EM>terminfo</EM> description, listing the various names for the terminal, separated by the "|" character. The <EM>terminal</EM> <EM>names</EM> section is terminated with an ASCII NUL character. @@ -164,41 +162,41 @@ capabilities are either 1 or 0 (true or false) according to whether the terminal supports the given capability or not. - Between the <EM>Boolean</EM> <EM>flags</EM> section and the <EM>number</EM> section, a null byte - will be inserted, if necessary, to ensure that the <EM>number</EM> section - begins on an even byte This is a relic of the PDP-11's word-addressed - architecture, originally designed to avoid traps induced by addressing - a word on an odd byte boundary. All short integers are aligned on a + Between the <EM>Boolean</EM> <EM>flags</EM> section and the <EM>number</EM> section, a null byte + will be inserted, if necessary, to ensure that the <EM>number</EM> section + begins on an even byte This is a relic of the PDP-11's word-addressed + architecture, originally designed to avoid traps induced by addressing + a word on an odd byte boundary. All short integers are aligned on a short word boundary. - The <EM>numbers</EM> section is similar to the <EM>Boolean</EM> <EM>flags</EM> section. Each - capability takes up two bytes, and is stored as a little-endian short + The <EM>numbers</EM> section is similar to the <EM>Boolean</EM> <EM>flags</EM> section. Each + capability takes up two bytes, and is stored as a little-endian short integer. - The <EM>strings</EM> section is also similar. Each capability is stored as a + The <EM>strings</EM> section is also similar. Each capability is stored as a short integer. The capability value is an index into the <EM>string</EM> <EM>table</EM>. The <EM>string</EM> <EM>table</EM> is the last section. It contains all of the values of string capabilities referenced in the <EM>strings</EM> section. Each string is null-terminated. Special characters in ^X or \c notation are stored in - their interpreted form, not the printing representation. Padding - information $<nn> and parameter information %x are stored intact in + their interpreted form, not the printing representation. Padding + information <STRONG>$<</STRONG><EM>nn</EM><STRONG>></STRONG> and parameter information <STRONG>%x</STRONG> are stored intact in uninterpreted form. </PRE><H3><a name="h3-Extended-Storage-Format">Extended Storage Format</a></H3><PRE> - The previous section describes the conventional terminfo binary format. + The previous section describes the conventional <EM>terminfo</EM> binary format. With some minor variations of the offsets (see PORTABILITY), the same binary format is used in all modern Unix systems. Each system uses a - predefined set of Boolean, number or string capabilities. + standard set of Boolean, numeric, or string capabilities. - The <EM>ncurses</EM> libraries and applications support extended terminfo binary - format, allowing users to define capabilities which are loaded at - runtime. This extension is made possible by using the fact that the - other implementations stop reading the terminfo data when they have - reached the end of the size given in the header. <EM>ncurses</EM> checks the - size, and if it exceeds that due to the predefined data, continues to - parse according to its own scheme. + The <EM>ncurses</EM> libraries and applications support extended <EM>terminfo</EM> binary + format, allowing users to define capabilities that are loaded at + runtime. This extension is made possible by using the fact that the + other implementations stop reading the <EM>terminfo</EM> data when they reach + the end of the size given in the header. <EM>ncurses</EM> checks the size, and + if it exceeds that specified in the header, continues to parse + according to its own scheme. First, it reads the extended header (5 short integers): @@ -212,7 +210,7 @@ (5) size of the extended string table in bytes - The count- and size-values for the extended string table include the + The count- and size-values for the extended string table include the extended capability <EM>names</EM> as well as extended capability <EM>values</EM>. Using the counts and sizes, <EM>ncurses</EM> allocates arrays and reads data for @@ -220,24 +218,22 @@ The extended string table contains values for string capabilities. After the end of these values, it contains the names for each of the - extended capabilities in order, e.g., Booleans, then numbers and - finally strings. + extended capabilities in order: Boolean, numeric, and string. - By storing terminal descriptions in this way, <EM>ncurses</EM> is able to + By storing terminal descriptions in this way, <EM>ncurses</EM> is able to provide a database useful with legacy applications, as well as - providing data for applications which need more than the predefined - capabilities. See <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> for an overview of the way <EM>ncurses</EM> uses - this extended information. + providing data for applications that require more information about a + terminal type than was anticipated by X/Open Curses. See <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> + for an overview of the way <EM>ncurses</EM> uses this extended information. - Applications which manipulate terminal data can use the definitions - described in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> which associate the long capability - names with members of a <STRONG>TERMTYPE</STRONG> structure. + Applications that manipulate terminal data can use the definitions + described in <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> associating the long capability names + with members of a <EM>TERMTYPE</EM> structure. </PRE><H3><a name="h3-Extended-Number-Format">Extended Number Format</a></H3><PRE> - On occasion, 16-bit signed integers are not large enough. With <EM>ncurses</EM> - 6.1, a new format was introduced by making a few changes to the legacy - format: + On occasion, 16-bit signed integers are not large enough. <EM>ncurses</EM> 6.1 + introduced a new format by making a few changes to the legacy format: <STRONG>o</STRONG> a different magic number (octal 01036) @@ -245,10 +241,10 @@ to signed 32-bit integers. To maintain compatibility, the library presents the same data - structures to direct users of the <STRONG>TERMTYPE</STRONG> structure as in previous + structures to direct users of the <EM>TERMTYPE</EM> structure as in previous formats. However, that cannot provide callers with the extended numbers. The library uses a similar but hidden data structure - <STRONG>TERMTYPE2</STRONG> to provide data for the terminfo functions. + <EM>TERMTYPE2</EM> to provide data for the <EM>terminfo</EM> functions. </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE> @@ -265,71 +261,71 @@ (resulting in extra unrecognized entries in the file) or the program may have been recompiled more recently than the database was updated (resulting in missing entries). The routine <STRONG>setupterm</STRONG> must be prepared - for both possibilities - this is why the numbers and sizes are - included. Also, new capabilities must always be added at the end of + for both possibilities - this is why the numbers and sizes are + included. Also, new capabilities must always be added at the end of the lists of Boolean, number, and string capabilities. </PRE><H3><a name="h3-Binary-Format">Binary Format</a></H3><PRE> - X/Open Curses does not specify a format for the terminfo database. - System V curses used a directory-tree of binary files, one per terminal + X/Open Curses does not specify a format for the <EM>terminfo</EM> database. + System V <EM>curses</EM> used a directory-tree of binary files, one per terminal description. - Despite the consistent use of little-endian for numbers and the - otherwise self-describing format, it is not wise to count on - portability of binary terminfo entries between commercial Unix - versions. The problem is that there are at least three versions of - terminfo (under HP-UX, AIX, and OSF/1) which diverged from System V - terminfo after SVr1, and have added extension capabilities to the - string table that (in the binary format) collide with System V and - X/Open Curses extensions. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for detailed discussion of - terminfo source compatibility issues. - - This implementation is by default compatible with the binary terminfo - format used by Solaris curses, except in a few less-used details where + Despite the consistent use of little-endian numbers and the otherwise + self-describing format, it is not wise to count on portability of + binary <EM>terminfo</EM> entries between commercial Unix versions. The problem + is that there are at least three versions of <EM>terminfo</EM> (under HP-UX, + AIX, and OSF/1) each of which diverged from System V <EM>terminfo</EM> after + SVr1, and added extension capabilities to the string table that (in the + binary format) collide with System V and X/Open Curses extensions. See + <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for detailed discussion of <EM>terminfo</EM> source compatibility + issues. + + This implementation is by default compatible with the binary <EM>terminfo</EM> + format used by Solaris <EM>curses</EM>, except in a few less-used details where it was found that the latter did not match X/Open Curses. The format used by the other Unix versions can be matched by building <EM>ncurses</EM> with different configuration options. </PRE><H3><a name="h3-Magic-Codes">Magic Codes</a></H3><PRE> - The magic number in a binary terminfo file is the first 16-bits (two - bytes). Besides making it more reliable for the library to check that - a file is terminfo, utilities such as <STRONG>file(1)</STRONG> also use that to tell - what the file-format is. System V defined more than one magic number, + The magic number in a binary <EM>terminfo</EM> file is the first 16 bits (two + bytes). Besides making it more reliable for the library to check that + a file is <EM>terminfo</EM>, utilities such as <STRONG>file(1)</STRONG> also use that to tell + what the file-format is. System V defined more than one magic number, with 0433, 0435 as screen-dumps (see <STRONG><A HREF="scr_dump.5.html">scr_dump(5)</A></STRONG>). This implementation uses 01036 as a continuation of that sequence, but with a different high-order byte to avoid confusion. - <STRONG>The</STRONG> <EM>TERMTYPE</EM> <STRONG>Structure</STRONG> - Direct access to the <STRONG>TERMTYPE</STRONG> structure is provided for legacy - applications. Portable applications should use the <STRONG>tigetflag</STRONG> and - related functions described in <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> for reading terminal - capabilities. + +</PRE><H3><a name="h3-The-TERMTYPE-Structure">The TERMTYPE Structure</a></H3><PRE> + Direct access to the <EM>TERMTYPE</EM> structure is provided for legacy + applications. Portable applications should use <STRONG><A HREF="curs_terminfo.3x.html">tigetflag(3x)</A></STRONG> and + related functions to read terminal capabilities. </PRE><H3><a name="h3-Mixed-case-Terminal-Names">Mixed-case Terminal Names</a></H3><PRE> - A small number of terminal descriptions use uppercase characters in - their names. If the underlying filesystem ignores the difference - between uppercase and lowercase, <EM>ncurses</EM> represents the "first - character" of the terminal name used as the intermediate level of a + A small number of terminal descriptions use uppercase characters in + their names. If the underlying file system ignores the difference + between uppercase and lowercase, <EM>ncurses</EM> represents the "first + character" of the terminal name used as the intermediate level of a directory tree in (two-character) hexadecimal form. </PRE><H3><a name="h3-Limits">Limits</a></H3><PRE> <EM>ncurses</EM> stores compiled terminal descriptions in three related formats, - described in the sections + described in the subsections - <STRONG>o</STRONG> <STRONG>LEGACY</STRONG> <STRONG>STORAGE</STRONG> <STRONG>FORMAT</STRONG>, and + <STRONG>o</STRONG> <STRONG>Legacy</STRONG> <STRONG>Storage</STRONG> <STRONG>Format</STRONG>, and - <STRONG>o</STRONG> <STRONG>EXTENDED</STRONG> <STRONG>STORAGE</STRONG> <STRONG>FORMAT</STRONG>, and + <STRONG>o</STRONG> <STRONG>Extended</STRONG> <STRONG>Storage</STRONG> <STRONG>Format</STRONG>, and - <STRONG>o</STRONG> <STRONG>EXTENDED</STRONG> <STRONG>NUMBER</STRONG> <STRONG>FORMAT</STRONG>. + <STRONG>o</STRONG> <STRONG>Extended</STRONG> <STRONG>Number</STRONG> <STRONG>Format</STRONG>. The legacy storage format and the extended number format differ by the - types of numeric capability which they can store (i.e., 16-bit versus - 32-bit integers). The extended storage format introduced by <EM>ncurses</EM> - 5.0 adds data to either of these formats. + types of numeric capability that they can store (for example, 16- + versus 32-bit integers). The extended storage format introduced by + <EM>ncurses</EM> 5.0 adds data to either of these formats. Some limitations apply: @@ -348,8 +344,8 @@ </PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE> - As an example, here is a description for the Lear-Siegler ADM-3, a - popular though rather stupid early terminal: + Here is a <EM>terminfo</EM> description of the Lear-Siegler ADM-3, a popular + though rather stupid early terminal. adm3a|lsi adm3a, am, @@ -358,7 +354,8 @@ cuf1=^L, cup=\E=%p1%{32}%+%c%p2%{32}%+%c, cuu1=^K, home=^^, ind=^J, - and a hexadecimal dump of the compiled terminal description: + A hexadecimal dump of its compiled terminal description (in legacy + format) follows. 0000 1a 01 10 00 02 00 03 00 82 00 31 00 61 64 6d 33 ........ ..1.adm3 0010 61 7c 6c 73 69 20 61 64 6d 33 61 00 00 01 50 00 a|lsi ad m3a...P. @@ -386,25 +383,22 @@ </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> Thomas E. Dickey - extended terminfo format for <EM>ncurses</EM> 5.0 + extended <EM>terminfo</EM> format for <EM>ncurses</EM> 5.0 hashed database support for <EM>ncurses</EM> 5.6 extended number support for <EM>ncurses</EM> 6.1 Eric S. Raymond - documented legacy terminfo format, e.g., from <EM>pcurses</EM>. + documented legacy <EM>terminfo</EM> format (that used by <EM>pcurses</EM>). </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="term.5.html">term(5)</A></STRONG> +ncurses 6.6 2025-08-16 <STRONG><A HREF="term.5.html">term(5)</A></STRONG> </PRE> <div class="nav"> <ul> <li><a href="#h2-NAME">NAME</a></li> -<li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li> <li><a href="#h2-DESCRIPTION">DESCRIPTION</a> <ul> <li><a href="#h3-Storage-Location">Storage Location</a></li> @@ -419,6 +413,7 @@ ncurses 6.5 2024-04-20 <STRONG>< <li><a href="#h3-setupterm">setupterm</a></li> <li><a href="#h3-Binary-Format">Binary Format</a></li> <li><a href="#h3-Magic-Codes">Magic Codes</a></li> +<li><a href="#h3-The-TERMTYPE-Structure">The TERMTYPE Structure</a></li> <li><a href="#h3-Mixed-case-Terminal-Names">Mixed-case Terminal Names</a></li> <li><a href="#h3-Limits">Limits</a></li> </ul> diff --git a/doc/html/man/term.7.html b/doc/html/man/term.7.html index 9a8858878771..b119732c8a2c 100644 --- a/doc/html/man/term.7.html +++ b/doc/html/man/term.7.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2011,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: term.7,v 1.48 2024/03/16 15:35:01 tom Exp @ + * @Id: term.7,v 1.52 2025/08/16 20:08:21 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>term 7 2024-03-16 ncurses 6.5 Miscellaneous</TITLE> +<TITLE>term 7 2025-08-16 ncurses 6.6 Miscellaneous</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">term 7 2024-03-16 ncurses 6.5 Miscellaneous</H1> +<H1 class="no-header">term 7 2025-08-16 ncurses 6.6 Miscellaneous</H1> <PRE> <STRONG><A HREF="term.7.html">term(7)</A></STRONG> Miscellaneous <STRONG><A HREF="term.7.html">term(7)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> term - conventions for naming terminal types @@ -76,69 +74,69 @@ In any case, you are free to override the system <EM>TERM</EM> setting to your taste in your shell profile. The <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> utility may be of assistance; - you can give it a set of rules for deducing or requesting a terminal + you can give it a set of rules for deducing or requesting a terminal type based on the tty device and baud rate. - Setting your own <EM>TERM</EM> value may also be useful if you have created a - custom entry incorporating options (such as visual bell or reverse- - video) which you wish to override the system default type for your + Setting your own <EM>TERM</EM> value may also be useful if you have created a + custom entry incorporating options (such as visual bell or reverse- + video) which you wish to override the system default type for your line. - Terminal type descriptions are stored as files of capability data - underneath /usr/share/terminfo. To browse a list of all terminal names + Terminal type descriptions are stored as files of capability data + underneath <EM>/usr/share/terminfo</EM>. To browse a list of all terminal names recognized by the system, do toe | more from your shell. These capability files are in a binary format optimized for retrieval speed (unlike the old text-based <STRONG>termcap</STRONG> format - they replace); to examine an entry, you must use the <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG> + they replace); to examine an entry, you must use the <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG> command. Invoke it as follows: infocmp <EM>entry</EM><STRONG>_</STRONG><EM>name</EM> - where <EM>entry</EM><STRONG>_</STRONG><EM>name</EM> is the name of the type you wish to examine (and the - name of its capability file the subdirectory of /usr/share/terminfo - named for its first letter). This command dumps a capability file in + where <EM>entry</EM><STRONG>_</STRONG><EM>name</EM> is the name of the type you wish to examine (and the + name of its capability file the subdirectory of <EM>/usr/share/terminfo</EM> + named for its first letter). This command dumps a capability file in the text format described by <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. - The first line of a <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> description gives the names by which - terminfo knows a terminal, separated by "|" (pipe-bar) characters with + The first line of a <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> description gives the names by which + terminfo knows a terminal, separated by "|" (pipe-bar) characters with the last name field terminated by a comma. The first name field is the type's <EM>primary</EM> <EM>name</EM>, and is the one to use when setting <EM>TERM</EM>. The last - name field (if distinct from the first) is actually a description of - the terminal type (it may contain blanks; the others must be single - words). Name fields between the first and last (if present) are + name field (if distinct from the first) is actually a description of + the terminal type (it may contain blanks; the others must be single + words). Name fields between the first and last (if present) are aliases for the terminal, usually historical names retained for compatibility. - There are some conventions for how to choose terminal primary names - that help keep them informative and unique. Here is a step-by-step + There are some conventions for how to choose terminal primary names + that help keep them informative and unique. Here is a step-by-step guide to naming terminals that also explains how to parse them: - First, choose a root name. The root will consist of a lower-case - letter followed by up to seven lower-case letters or digits. You need - to avoid using punctuation characters in root names, because they are + First, choose a root name. The root will consist of a lower-case + letter followed by up to seven lower-case letters or digits. You need + to avoid using punctuation characters in root names, because they are used and interpreted as filenames and shell meta-characters (such as !, $, *, ?, etc.) embedded in them may cause odd and unhelpful behavior. The slash (/), or any other character that may be interpreted by anyone's file system (\, $, [, ]), is especially dangerous (terminfo is - platform-independent, and choosing names with special characters could - someday make life difficult for users of a future port). The dot (.) - character is relatively safe as long as there is at most one per root + platform-independent, and choosing names with special characters could + someday make life difficult for users of a future port). The dot (.) + character is relatively safe as long as there is at most one per root name; some historical terminfo names use it. - The root name for a terminal or workstation console type should almost - always begin with a vendor prefix (such as <STRONG>hp</STRONG> for Hewlett-Packard, <STRONG>wy</STRONG> - for Wyse, or <STRONG>att</STRONG> for AT&T terminals), or a common name of the terminal - line (<STRONG>vt</STRONG> for the VT series of terminals from DEC, or <STRONG>sun</STRONG> for Sun - Microsystems workstation consoles, or <STRONG>regent</STRONG> for the ADDS Regent - series. You can list the terminfo tree to see what prefixes are - already in common use. The root name prefix should be followed when + The root name for a terminal or workstation console type should almost + always begin with a vendor prefix (such as <STRONG>hp</STRONG> for Hewlett-Packard, <STRONG>wy</STRONG> + for Wyse, or <STRONG>att</STRONG> for AT&T terminals), or a common name of the terminal + line (<STRONG>vt</STRONG> for the VT series of terminals from DEC, or <STRONG>sun</STRONG> for Sun + Microsystems workstation consoles, or <STRONG>regent</STRONG> for the ADDS Regent + series. You can list the terminfo tree to see what prefixes are + already in common use. The root name prefix should be followed when appropriate by a model number; thus <STRONG>vt100</STRONG>, <STRONG>hp2621</STRONG>, <STRONG>wy50</STRONG>. - The root name for a PC-Unix console type should be the OS name, i.e., - <STRONG>linux</STRONG>, <STRONG>bsdos</STRONG>, <STRONG>freebsd</STRONG>, <STRONG>netbsd</STRONG>. It should <EM>not</EM> be <STRONG>console</STRONG> or any other + The root name for a PC-Unix console type should be the OS name, i.e., + <STRONG>linux</STRONG>, <STRONG>bsdos</STRONG>, <STRONG>freebsd</STRONG>, <STRONG>netbsd</STRONG>. It should <EM>not</EM> be <STRONG>console</STRONG> or any other generic that might cause confusion in a multi-platform environment! If a model number follows, it should indicate either the OS release level or the console driver release level. @@ -161,7 +159,7 @@ -m Mono mode - suppress color support. - -na No arrow keys - termcap ignores arrow keys which are actually + -na No arrow keys - termcap ignores arrow keys which are actually there on the terminal, so the user can use the arrow keys locally. -nam No auto-margin - suppress am capability. @@ -180,13 +178,13 @@ -w Wide; terminal is in 132-column mode. - Conventionally, if your terminal type is a variant intended to specify - a line height, that suffix should go first. So, for a hypothetical - FuBarCo model 2317 terminal in 30-line mode with reverse video, best + Conventionally, if your terminal type is a variant intended to specify + a line height, that suffix should go first. So, for a hypothetical + FuBarCo model 2317 terminal in 30-line mode with reverse video, best form would be <STRONG>fubar-30-rv</STRONG> (rather than, say, "fubar-rv-30"). - Terminal types that are written not as standalone entries, but rather - as components to be plugged into other entries via <STRONG>use</STRONG> capabilities, + Terminal types that are written not as standalone entries, but rather + as components to be plugged into other entries via <STRONG>use</STRONG> capabilities, are distinguished by using embedded plus signs rather than dashes. Commands which use a terminal type to control display often accept a -T @@ -214,9 +212,7 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="term.5.html">term(5)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="term.7.html">term(7)</A></STRONG> +ncurses 6.6 2025-08-16 <STRONG><A HREF="term.7.html">term(7)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/term_variables.3x.html b/doc/html/man/term_variables.3x.html index 99b6786bca48..84d85ca19fc5 100644 --- a/doc/html/man/term_variables.3x.html +++ b/doc/html/man/term_variables.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 2010-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: term_variables.3x,v 1.36 2024/03/16 15:35:01 tom Exp @ + * @Id: term_variables.3x,v 1.44 2025/11/12 01:27:41 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>term_variables 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>term_variables 3x 2025-11-11 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">term_variables 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">term_variables 3x 2025-11-11 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> Library calls <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>SP</STRONG>, <STRONG>acs_map</STRONG>, <STRONG>boolcodes</STRONG>, <STRONG>boolfnames</STRONG>, <STRONG>boolnames</STRONG>, <STRONG>cur_term</STRONG>, <STRONG>numcodes</STRONG>, <STRONG>numfnames</STRONG>, <STRONG>numnames</STRONG>, <STRONG>strcodes</STRONG>, <STRONG>strfnames</STRONG>, <STRONG>strnames</STRONG>, <STRONG>ttytype</STRONG> - <EM>terminfo</EM> @@ -78,105 +76,102 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - This page summarizes variables provided by the <STRONG>curses</STRONG> library's low- - level terminfo interface. A more complete description is given in the + This page summarizes variables provided by the <EM>curses</EM> library's lower- + level <EM>terminfo</EM> interface. Locate a more complete description in the <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG> manual page. - Depending on the configuration, these may be actual variables, or - macros (see <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>) which provide read-only access to - <EM>curses</EM>'s state. In either case, applications should treat them as - read-only to avoid confusing the library. + Depending on <EM>ncurses</EM>'s build-time configuration, these may be actual + variables, or macros (see <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>) that provide read-only + access to <EM>curses</EM>'s state. In either case, applications should treat + them as read-only to avoid confusing the library. </PRE><H3><a name="h3-Alternate-Character-Set-Mapping">Alternate Character Set Mapping</a></H3><PRE> - After initializing the curses or terminfo interfaces, the <STRONG>acs_map</STRONG> array - holds information used to translate cells with the <STRONG>A_ALTCHARSET</STRONG> video + After initializing the <EM>curses</EM> or <EM>terminfo</EM> interfaces, the <STRONG>acs_map</STRONG> array + holds information used to translate cells with the <STRONG>A_ALTCHARSET</STRONG> video attribute into line-drawing characters. The encoding of the information in this array has changed periodically. Application developers need only know that it is used for the "ACS_" - constants in <curses.h>. + constants in <EM>curses.h</EM>. - The comparable data for the wide-character library is a private - variable. + The comparable data for the wide-character library are not exposed as + symbols in the API. </PRE><H3><a name="h3-Current-Terminal-Data">Current Terminal Data</a></H3><PRE> - After initializing the curses or terminfo interfaces, the <STRONG>cur_term</STRONG> - contains data describing the current terminal. This variable is also - set as a side-effect of <STRONG><A HREF="curs_initscr.3x.html">set_term(3x)</A></STRONG> and <STRONG><A HREF="curs_initscr.3x.html">delscreen(3x)</A></STRONG>. + After initializing the <EM>curses</EM> or <EM>terminfo</EM> interfaces, <STRONG>cur_term</STRONG> contains + data describing the current terminal. It is also updated as a side + effect of <STRONG><A HREF="curs_initscr.3x.html">set_term(3x)</A></STRONG> and <STRONG><A HREF="curs_initscr.3x.html">delscreen(3x)</A></STRONG>. - It is possible to save a value of <STRONG>cur_term</STRONG> for subsequent use as a - parameter to <STRONG>set_term</STRONG>, for switching between screens. Alternatively, - one can save the return value from <STRONG>newterm</STRONG> or <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to reuse in - <STRONG>set_term</STRONG>. + It is possible to save a value of <STRONG>cur_term</STRONG> for subsequent use as a + parameter to <STRONG><A HREF="curs_initscr.3x.html">set_term(3x)</A></STRONG> for switching between screens. + Alternatively, one can save the return value from <STRONG><A HREF="curs_initscr.3x.html">newterm(3x)</A></STRONG> or + <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to reuse in <STRONG><A HREF="curs_initscr.3x.html">set_term(3x)</A></STRONG>. </PRE><H3><a name="h3-terminfo-Lookup-Tables"><EM>terminfo</EM> Lookup Tables</a></H3><PRE> - The <STRONG><A HREF="tic.1m.html">tic(1)</A></STRONG> and <STRONG><A HREF="infocmp.1m.html">infocmp(1)</A></STRONG> programs use lookup tables for the long and - short names of terminfo capabilities, as well as the corresponding - names for termcap capabilities. These are available to other - applications, although the hash-tables used by the terminfo and termcap - functions are not available. - - The long terminfo capability names use a "f" (eff) in their names: - <STRONG>boolfnames</STRONG>, <STRONG>numfnames</STRONG>, and <STRONG>strfnames</STRONG>. + The <STRONG><A HREF="tic.1m.html">tic(1)</A></STRONG> and <STRONG><A HREF="infocmp.1m.html">infocmp(1)</A></STRONG> programs use lookup tables for the long and + short names of <EM>terminfo</EM> capabilities, as well as the corresponding + names for <EM>termcap</EM> capabilities. These are available to other + applications, though the hash tables used by the <EM>terminfo</EM> and <EM>termcap</EM> + functions are not. - These are the short names for terminfo capabilities: <STRONG>boolnames</STRONG>, - <STRONG>numnames</STRONG>, and <STRONG>strnames</STRONG>. - - These are the corresponding names used for termcap descriptions: - <STRONG>boolcodes</STRONG>, <STRONG>numcodes</STRONG>, and <STRONG>strcodes</STRONG>. + <EM>terminfo</EM> stores capability names in arrays with an "f" (eff) in their + names: <STRONG>boolfnames</STRONG>, <STRONG>numfnames</STRONG>, and <STRONG>strfnames</STRONG>. It stores the briefer + capability codes in arrays without the "f": <STRONG>boolnames</STRONG>, <STRONG>numnames</STRONG>, and + <STRONG>strnames</STRONG>. The corresponding <EM>termcap</EM> capability codes are stored in + <STRONG>boolcodes</STRONG>, <STRONG>numcodes</STRONG>, and <STRONG>strcodes</STRONG>. <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> catalogs these. </PRE><H3><a name="h3-Terminal-Type">Terminal Type</a></H3><PRE> A terminal description begins with one or more terminal names separated - by "|" (vertical bars). On initialization of the curses or terminfo - interfaces, <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> copies the terminal names to the array + by "|" (vertical bars). On initialization of the <EM>curses</EM> or <EM>terminfo</EM> + interfaces, <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> copies the terminal name to the array <STRONG>ttytype</STRONG>. </PRE><H3><a name="h3-terminfo-Names"><EM>terminfo</EM> Names</a></H3><PRE> - In addition to the variables, <STRONG><term.h></STRONG> also defines a symbol for each - terminfo capability <EM>long</EM> <EM>name</EM>. These are in terms of the symbol <STRONG>CUR</STRONG>, - which is defined + In addition to the variables, <EM>term.h</EM> also defines a symbol for each + <EM>terminfo</EM> capability name. These are in terms of the symbol <STRONG>CUR</STRONG>, which + is defined - #define CUR ((TERMTYPE *)(cur_term))-> + #define CUR ((TERMTYPE *)(cur_term))-> - These symbols provide a faster method of accessing terminfo - capabilities than using <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG>, etc. + These symbols provide a faster method of accessing <EM>terminfo</EM> + capabilities than using, for example, <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG>. - The actual definition of <STRONG>CUR</STRONG> depends upon the implementation, but each - terminfo library provides these long names defined to point into the - current terminal description loaded into memory. + The definition of <STRONG>CUR</STRONG> is implementation-dependent, but each <EM>terminfo</EM> + library defines these names to point into the in-memory description of + the current terminal. For example, in <EM>ncurses</EM>, the expressions + <STRONG>tigetstr("key_dc")</STRONG> and "<STRONG>CUR</STRONG> <STRONG>Strings[59]</STRONG>" are equivalent. -</PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - The low-level terminfo interface is initialized using <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>. - The upper-level curses interface uses the low-level terminfo interface, - internally. +</PRE><H3><a name="h3-terminfo-and-curses"><EM>terminfo</EM> and curses</a></H3><PRE> + <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> initializes the lower-level <EM>terminfo</EM> interface. The + higher-level <EM>curses</EM> interface uses the <EM>terminfo</EM> interface internally; + the symbol <STRONG>SP</STRONG> bridges the <EM>curses</EM> <EM>SCREEN</EM> type with the <EM>terminfo</EM> <EM>TERMINAL</EM> + type. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses does not describe any of these except for <STRONG>cur_term</STRONG>. (The - inclusion of <STRONG>cur_term</STRONG> appears to be an oversight, since other - comparable low-level information is omitted by X/Open). + X/Open Curses does not describe any of these symbols except for + <EM>cur</EM><STRONG>_</STRONG><EM>term</EM>. (The inclusion of <EM>cur</EM><STRONG>_</STRONG><EM>term</EM> appears to be an oversight, since + other comparable low-level information is omitted by X/Open.) - Other implementations may have comparable variables. Some + Other implementations may have comparable variables. Some implementations provide the variables in their libraries, but omit them from the header files. - All implementations which provide terminfo interfaces add definitions - as described in the <STRONG>Terminfo</STRONG> <STRONG>Names</STRONG> section. Most, but not all, base - the definition upon the <STRONG>cur_term</STRONG> variable. + All implementations that provide <EM>terminfo</EM> interfaces add definitions as + described in the "<EM>terminfo</EM> Names" section above. Most, but not all, + base the definition upon the <EM>cur</EM><STRONG>_</STRONG><EM>term</EM> variable. </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG><A HREF="curs_threads.3x.html">curs_threads(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -189,9 +184,9 @@ ncurses 6.5 2024-03-16 <STRONG><A HREF="ter <li><a href="#h3-terminfo-Lookup-Tables">terminfo Lookup Tables</a></li> <li><a href="#h3-Terminal-Type">Terminal Type</a></li> <li><a href="#h3-terminfo-Names">terminfo Names</a></li> +<li><a href="#h3-terminfo-and-curses">terminfo and curses</a></li> </ul> </li> -<li><a href="#h2-NOTES">NOTES</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> diff --git a/doc/html/man/terminfo.5.html b/doc/html/man/terminfo.5.html index 67061141faca..0fe01942c9ec 100644 --- a/doc/html/man/terminfo.5.html +++ b/doc/html/man/terminfo.5.html @@ -1,11 +1,14 @@ <!-- * t * DO NOT EDIT THIS FILE BY HAND! - * It is generated from terminfo.head, ./../include/Caps ./../include/Caps-ncurses, and terminfo.tail. - * Note: this must be run through tbl before nroff. - * The magic cookie on the first line triggers this under some man programs. + * man/MKterminfo.sh generated it from: + * terminfo.head, ./../include/Caps, ./../include/Caps-ncurses, + * and terminfo.tail. + * Note: this document must be run through tbl before nroff or troff. + * Some man(1) programs recognize the token in the first-line comment + * as directing them to arrange such a pipeline. **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -32,25 +35,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: terminfo.head,v 1.65 2024/04/20 21:14:00 tom Exp @ + * @Id: terminfo.head,v 1.69 2025/08/16 21:50:23 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>terminfo 5 2024-04-20 ncurses 6.5 File formats</TITLE> +<TITLE>terminfo 5 2025-08-16 ncurses 6.6 File formats</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">terminfo 5 2024-04-20 ncurses 6.5 File formats</H1> +<H1 class="no-header">terminfo 5 2025-08-16 ncurses 6.6 File formats</H1> <PRE> <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> File formats <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>terminfo</STRONG> - terminal capability database @@ -71,7 +72,7 @@ have, by specifying how to perform screen operations, and by specifying padding requirements and initialization sequences. - This document describes <EM>ncurses</EM> version 6.5 (patch 20240427). + This document describes <EM>ncurses</EM> version 6.6 (patch 20251230). </PRE><H3><a name="h3-terminfo-Entry-Syntax"><EM>terminfo</EM> Entry Syntax</a></H3><PRE> @@ -107,10 +108,10 @@ This implementation is not so strict; it allows mixed case in the primary name and aliases. If the last name has no embedded blanks, - it allows that to be both an alias and a verbose name (but will + it allows that to be both an alias and a verbose name (but will warn about this ambiguity). - <STRONG>o</STRONG> Lines beginning with a "#" in the first column are treated as + <STRONG>o</STRONG> Lines beginning with a "#" in the first column are treated as comments. While comment lines are valid at any point, the output of <STRONG>captoinfo</STRONG> @@ -121,8 +122,8 @@ using the following conventions. The particular piece of hardware making up the terminal should have a root name, thus "hp2621". This name should not contain hyphens. Modes that the hardware can be in, or - user preferences, should be indicated by appending a hyphen and a mode - suffix. Thus, a vt100 in 132-column mode would be vt100-w. The + user preferences, should be indicated by appending a hyphen and a mode + suffix. Thus, a vt100 in 132-column mode would be vt100-w. The following suffixes should be used where possible: <STRONG>Suffix</STRONG> <STRONG>Example</STRONG> <STRONG>Meaning</STRONG> @@ -145,51 +146,51 @@ </PRE><H3><a name="h3-terminfo-Capabilities-Syntax"><EM>terminfo</EM> Capabilities Syntax</a></H3><PRE> - The terminfo entry consists of several <EM>capabilities</EM>, i.e., features - that the terminal has, or methods for exercising the terminal's + The terminfo entry consists of several <EM>capabilities</EM>, i.e., features + that the terminal has, or methods for exercising the terminal's features. After the first field (giving the name(s) of the terminal entry), there should be one or more <EM>capability</EM> fields. These are Boolean, numeric or string names with corresponding values: - <STRONG>o</STRONG> Boolean capabilities are true when present, false when absent. + <STRONG>o</STRONG> Boolean capabilities are true when present, false when absent. There is no explicit value for Boolean capabilities. - <STRONG>o</STRONG> Numeric capabilities have a "#" following the name, then an + <STRONG>o</STRONG> Numeric capabilities have a "#" following the name, then an unsigned decimal integer value. - <STRONG>o</STRONG> String capabilities have a "=" following the name, then an string + <STRONG>o</STRONG> String capabilities have a "=" following the name, then an string of characters making up the capability value. - String capabilities can be split into multiple lines, just as the - fields comprising a terminal entry can be split into multiple - lines. While blanks between fields are ignored, blanks embedded - within a string value are retained, except for leading blanks on a + String capabilities can be split into multiple lines, just as the + fields comprising a terminal entry can be split into multiple + lines. While blanks between fields are ignored, blanks embedded + within a string value are retained, except for leading blanks on a line. - Any capability can be <EM>canceled</EM>, i.e., suppressed from the terminal + Any capability can be <EM>canceled</EM>, i.e., suppressed from the terminal entry, by following its name with "@" rather than a capability value. </PRE><H3><a name="h3-Similar-Terminals">Similar Terminals</a></H3><PRE> - If there are two very similar terminals, one (the variant) can be - defined as being just like the other (the base) with certain - exceptions. In the definition of the variant, the string capability + If there are two very similar terminals, one (the variant) can be + defined as being just like the other (the base) with certain + exceptions. In the definition of the variant, the string capability <STRONG>use</STRONG> can be given with the name of the base terminal: - <STRONG>o</STRONG> The capabilities given before <STRONG>use</STRONG> override those in the base type + <STRONG>o</STRONG> The capabilities given before <STRONG>use</STRONG> override those in the base type named by <STRONG>use</STRONG>. - <STRONG>o</STRONG> If there are multiple <STRONG>use</STRONG> capabilities, they are merged in reverse - order. That is, the rightmost <STRONG>use</STRONG> reference is processed first, + <STRONG>o</STRONG> If there are multiple <STRONG>use</STRONG> capabilities, they are merged in reverse + order. That is, the rightmost <STRONG>use</STRONG> reference is processed first, then the one to its left, and so forth. - <STRONG>o</STRONG> Capabilities given explicitly in the entry override those brought + <STRONG>o</STRONG> Capabilities given explicitly in the entry override those brought in by <STRONG>use</STRONG> references. - A capability can be canceled by placing <STRONG>xx@</STRONG> to the left of the use - reference that imports it, where <EM>xx</EM> is the capability. For example, + A capability can be canceled by placing <STRONG>xx@</STRONG> to the left of the use + reference that imports it, where <EM>xx</EM> is the capability. For example, the entry 2621-nl, smkx@, rmkx@, use=2621, @@ -200,15 +201,15 @@ user preferences. An entry included via <STRONG>use</STRONG> can contain canceled capabilities, which have - the same effect as if those cancels were inline in the using terminal + the same effect as if those cancels were inline in the using terminal entry. -</PRE><H3><a name="h3-Predefined-Capabilities">Predefined Capabilities</a></H3><PRE> - Tables of capabilities <EM>ncurses</EM> recognizes in a <EM>terminfo</EM> terminal type +</PRE><H3><a name="h3-Standard-Capabilities">Standard Capabilities</a></H3><PRE> + Tables of capabilities <EM>ncurses</EM> recognizes in a <EM>terminfo</EM> terminal type description and available to <EM>terminfo</EM>-using code follow. - <STRONG>o</STRONG> The capability name identifies the symbol by which the programmer + <STRONG>o</STRONG> The capability name identifies the symbol by which the programmer using the <EM>terminfo</EM> API accesses the capability. <STRONG>o</STRONG> The TI (<EM>terminfo</EM>) code is the short name used by a person composing @@ -219,38 +220,36 @@ uses identical or very similar names). Semantics are also intended to match those of the specification. - <EM>terminfo</EM> codes have no hard length limit, but <EM>ncurses</EM> maintains an - informal one of 5 characters to keep them short and to allow the - tabs in the source file <EM>Caps</EM> to line up nicely. (Some standard + <EM>terminfo</EM> codes have no hard length limit, but <EM>ncurses</EM> maintains an + informal one of 5 characters to keep them short and to allow the + tabs in the source file <EM>Caps</EM> to line up nicely. (Some standard codes exceed this limit regardless.) - <STRONG>o</STRONG> The TC (<EM>termcap</EM>) code is that used by the corresponding API of - <EM>ncurses</EM>. (Some capabilities are new, and have names that BSD + <STRONG>o</STRONG> The TC (<EM>termcap</EM>) code is that used by the corresponding API of + <EM>ncurses</EM>. (Some capabilities are new, and have names that BSD <EM>termcap</EM> did not originate.) - <STRONG>o</STRONG> The description field attempts to convey the capability's + <STRONG>o</STRONG> The description field attempts to convey the capability's semantics. The description field employs a handful of notations. <STRONG>(P)</STRONG> indicates that padding may be specified. - <STRONG>(P*)</STRONG> indicates that padding may vary in proportion to the number of + <STRONG>(P*)</STRONG> indicates that padding may vary in proportion to the number of output lines affected. - <STRONG>#</STRONG><EM>i</EM> indicates the <EM>i</EM>th parameter of a string capability; the - programmer should pass the string to <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> with the + <STRONG>#</STRONG><EM>i</EM> indicates the <EM>i</EM>th parameter of a string capability; the + programmer should pass the string to <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> with the parameters listed. - If the description lists no parameters, passing the string to - <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> may produce unexpected behavior, for instance if the + If the description lists no parameters, passing the string to + <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> may produce unexpected behavior, for instance if the string contains percent signs. <STRONG>Code</STRONG> <STRONG>Boolean</STRONG> <STRONG>Capability</STRONG> <STRONG>Name</STRONG> <STRONG>TI</STRONG> <STRONG>TC</STRONG> <STRONG>Description</STRONG> ------------------------------------------------------------------------ - - <STRONG>auto_left_margin</STRONG> <STRONG>bw</STRONG> <STRONG>bw</STRONG> cub1 wraps from column 0 to last column <STRONG>auto_right_margin</STRONG> <STRONG>am</STRONG> <STRONG>am</STRONG> terminal has automatic margins @@ -316,7 +315,6 @@ resolution <STRONG>Code</STRONG> - <STRONG>Numeric</STRONG> <STRONG>Capability</STRONG> <STRONG>Name</STRONG> <STRONG>TI</STRONG> <STRONG>TC</STRONG> <STRONG>Description</STRONG> ------------------------------------------------------------------------ <STRONG>columns</STRONG> <STRONG>cols</STRONG> <STRONG>co</STRONG> number of columns in a line @@ -382,7 +380,6 @@ <STRONG>wide_char_size</STRONG> <STRONG>widcs</STRONG> <STRONG>Yn</STRONG> character step size when in double wide mode <STRONG>buttons</STRONG> <STRONG>btns</STRONG> <STRONG>BT</STRONG> number of buttons on mouse - <STRONG>bit_image_entwining</STRONG> <STRONG>bitwin</STRONG> <STRONG>Yo</STRONG> number of passes for each bit- image row <STRONG>bit_image_type</STRONG> <STRONG>bitype</STRONG> <STRONG>Yp</STRONG> type of bit-image device @@ -448,7 +445,6 @@ cup <STRONG>exit_delete_mode</STRONG> <STRONG>rmdc</STRONG> <STRONG>ed</STRONG> end delete mode <STRONG>exit_insert_mode</STRONG> <STRONG>rmir</STRONG> <STRONG>ei</STRONG> exit insert mode - <STRONG>exit_standout_mode</STRONG> <STRONG>rmso</STRONG> <STRONG>se</STRONG> exit standout mode <STRONG>exit_underline_mode</STRONG> <STRONG>rmul</STRONG> <STRONG>ue</STRONG> exit underline mode <STRONG>flash_screen</STRONG> <STRONG>flash</STRONG> <STRONG>vb</STRONG> visible bell (may not move @@ -471,7 +467,6 @@ <STRONG>key_dc</STRONG> <STRONG>kdch1</STRONG> <STRONG>kD</STRONG> delete-character key <STRONG>key_dl</STRONG> <STRONG>kdl1</STRONG> <STRONG>kL</STRONG> delete-line key <STRONG>key_down</STRONG> <STRONG>kcud1</STRONG> <STRONG>kd</STRONG> down-arrow key - <STRONG>key_eic</STRONG> <STRONG>krmir</STRONG> <STRONG>kM</STRONG> sent by rmir or smir in insert mode <STRONG>key_eol</STRONG> <STRONG>kel</STRONG> <STRONG>kE</STRONG> clear-to-end-of-line key @@ -499,8 +494,8 @@ <STRONG>key_sr</STRONG> <STRONG>kri</STRONG> <STRONG>kR</STRONG> scroll-backward key <STRONG>key_stab</STRONG> <STRONG>khts</STRONG> <STRONG>kT</STRONG> set-tab key <STRONG>key_up</STRONG> <STRONG>kcuu1</STRONG> <STRONG>ku</STRONG> up-arrow key - <STRONG>keypad_local</STRONG> <STRONG>rmkx</STRONG> <STRONG>ke</STRONG> leave keyboard transmit mode - <STRONG>keypad_xmit</STRONG> <STRONG>smkx</STRONG> <STRONG>ks</STRONG> enter keyboard transmit mode + <STRONG>keypad_local</STRONG> <STRONG>rmkx</STRONG> <STRONG>ke</STRONG> leave keypad transmit mode + <STRONG>keypad_xmit</STRONG> <STRONG>smkx</STRONG> <STRONG>ks</STRONG> enter keypad transmit mode <STRONG>lab_f0</STRONG> <STRONG>lf0</STRONG> <STRONG>l0</STRONG> label on function key f0 if not f0 <STRONG>lab_f1</STRONG> <STRONG>lf1</STRONG> <STRONG>l1</STRONG> label on function key f1 if @@ -513,8 +508,6 @@ not f3 <STRONG>lab_f4</STRONG> <STRONG>lf4</STRONG> <STRONG>l4</STRONG> label on function key f4 if not f4 - - <STRONG>lab_f5</STRONG> <STRONG>lf5</STRONG> <STRONG>l5</STRONG> label on function key f5 if not f5 <STRONG>lab_f6</STRONG> <STRONG>lf6</STRONG> <STRONG>l6</STRONG> label on function key f6 if @@ -525,6 +518,7 @@ not f8 <STRONG>lab_f9</STRONG> <STRONG>lf9</STRONG> <STRONG>l9</STRONG> label on function key f9 if not f9 + <STRONG>meta_off</STRONG> <STRONG>rmm</STRONG> <STRONG>mo</STRONG> turn off meta mode <STRONG>meta_on</STRONG> <STRONG>smm</STRONG> <STRONG>mm</STRONG> turn on meta mode (8th-bit on) <STRONG>newline</STRONG> <STRONG>nel</STRONG> <STRONG>nw</STRONG> newline (behave like cr @@ -554,7 +548,6 @@ <STRONG>repeat_char</STRONG> <STRONG>rep</STRONG> <STRONG>rp</STRONG> repeat char #1 #2 times (P*) <STRONG>reset_1string</STRONG> <STRONG>rs1</STRONG> <STRONG>r1</STRONG> reset string <STRONG>reset_2string</STRONG> <STRONG>rs2</STRONG> <STRONG>r2</STRONG> reset string - <STRONG>reset_3string</STRONG> <STRONG>rs3</STRONG> <STRONG>r3</STRONG> reset string <STRONG>reset_file</STRONG> <STRONG>rf</STRONG> <STRONG>rf</STRONG> name of reset file <STRONG>restore_cursor</STRONG> <STRONG>rc</STRONG> <STRONG>rc</STRONG> restore cursor to position of @@ -580,7 +573,6 @@ <STRONG>init_prog</STRONG> <STRONG>iprog</STRONG> <STRONG>iP</STRONG> path name of program for initialization <STRONG>key_a1</STRONG> <STRONG>ka1</STRONG> <STRONG>K1</STRONG> upper left of keypad - <STRONG>key_a3</STRONG> <STRONG>ka3</STRONG> <STRONG>K3</STRONG> upper right of keypad <STRONG>key_b2</STRONG> <STRONG>kb2</STRONG> <STRONG>K2</STRONG> center of keypad <STRONG>key_c1</STRONG> <STRONG>kc1</STRONG> <STRONG>K4</STRONG> lower left of keypad @@ -630,7 +622,6 @@ <STRONG>key_save</STRONG> <STRONG>ksav</STRONG> <STRONG>&6</STRONG> save key <STRONG>key_suspend</STRONG> <STRONG>kspd</STRONG> <STRONG>&7</STRONG> suspend key <STRONG>key_undo</STRONG> <STRONG>kund</STRONG> <STRONG>&8</STRONG> undo key - <STRONG>key_sbeg</STRONG> <STRONG>kBEG</STRONG> <STRONG>&9</STRONG> shifted begin key <STRONG>key_scancel</STRONG> <STRONG>kCAN</STRONG> <STRONG>&0</STRONG> shifted cancel key <STRONG>key_scommand</STRONG> <STRONG>kCMD</STRONG> <STRONG>*1</STRONG> shifted command key @@ -646,7 +637,6 @@ <STRONG>key_sfind</STRONG> <STRONG>kFND</STRONG> <STRONG>*0</STRONG> shifted find key <STRONG>key_shelp</STRONG> <STRONG>kHLP</STRONG> <STRONG>#1</STRONG> shifted help key <STRONG>key_shome</STRONG> <STRONG>kHOM</STRONG> <STRONG>#2</STRONG> shifted home key - <STRONG>key_sic</STRONG> <STRONG>kIC</STRONG> <STRONG>#3</STRONG> shifted insert-character key <STRONG>key_sleft</STRONG> <STRONG>kLFT</STRONG> <STRONG>#4</STRONG> shifted left-arrow key <STRONG>key_smessage</STRONG> <STRONG>kMSG</STRONG> <STRONG>%a</STRONG> shifted message key @@ -696,7 +686,6 @@ <STRONG>key_f40</STRONG> <STRONG>kf40</STRONG> <STRONG>FU</STRONG> F40 function key <STRONG>key_f41</STRONG> <STRONG>kf41</STRONG> <STRONG>FV</STRONG> F41 function key <STRONG>key_f42</STRONG> <STRONG>kf42</STRONG> <STRONG>FW</STRONG> F42 function key - <STRONG>key_f43</STRONG> <STRONG>kf43</STRONG> <STRONG>FX</STRONG> F43 function key <STRONG>key_f44</STRONG> <STRONG>kf44</STRONG> <STRONG>FY</STRONG> F44 function key <STRONG>key_f45</STRONG> <STRONG>kf45</STRONG> <STRONG>FZ</STRONG> F45 function key @@ -712,7 +701,6 @@ <STRONG>key_f55</STRONG> <STRONG>kf55</STRONG> <STRONG>Fj</STRONG> F55 function key <STRONG>key_f56</STRONG> <STRONG>kf56</STRONG> <STRONG>Fk</STRONG> F56 function key <STRONG>key_f57</STRONG> <STRONG>kf57</STRONG> <STRONG>Fl</STRONG> F57 function key - <STRONG>key_f58</STRONG> <STRONG>kf58</STRONG> <STRONG>Fm</STRONG> F58 function key <STRONG>key_f59</STRONG> <STRONG>kf59</STRONG> <STRONG>Fn</STRONG> F59 function key <STRONG>key_f60</STRONG> <STRONG>kf60</STRONG> <STRONG>Fo</STRONG> F60 function key @@ -776,9 +764,7 @@ <STRONG>define_char</STRONG> <STRONG>defc</STRONG> <STRONG>ZE</STRONG> Define a character #1, #2 dots wide, descender #3 <STRONG>enter_doublewide_mode</STRONG> <STRONG>swidm</STRONG> <STRONG>ZF</STRONG> Enter double-wide mode - <STRONG>enter_draft_quality</STRONG> <STRONG>sdrfq</STRONG> <STRONG>ZG</STRONG> Enter draft-quality mode - <STRONG>enter_italics_mode</STRONG> <STRONG>sitm</STRONG> <STRONG>ZH</STRONG> Enter italic mode <STRONG>enter_leftward_mode</STRONG> <STRONG>slm</STRONG> <STRONG>ZI</STRONG> Start leftward carriage motion <STRONG>enter_micro_mode</STRONG> <STRONG>smicm</STRONG> <STRONG>ZJ</STRONG> Start micro-motion mode @@ -863,6 +849,7 @@ using ANSI escape <STRONG>set_a_background</STRONG> <STRONG>setab</STRONG> <STRONG>AB</STRONG> Set background color to #1, using ANSI escape + <STRONG>pkey_plab</STRONG> <STRONG>pfxl</STRONG> <STRONG>xl</STRONG> Program function key #1 to type string #2 and show string #3 @@ -910,7 +897,6 @@ binary-compatible with System V terminfo entries after SVr4.1; beware! <STRONG>Code</STRONG> - <STRONG>String</STRONG> <STRONG>Capability</STRONG> <STRONG>Name</STRONG> <STRONG>TI</STRONG> <STRONG>TC</STRONG> <STRONG>Description</STRONG> ------------------------------------------------------------------------ <STRONG>enter_horizontal_hl_mode</STRONG> <STRONG>ehhlm</STRONG> <STRONG>Xh</STRONG> Enter horizontal highlight @@ -929,51 +915,54 @@ </PRE><H3><a name="h3-User-Defined-Capabilities">User-Defined Capabilities</a></H3><PRE> - The preceding section listed the <EM>predefined</EM> capabilities. They deal - with some special features for terminals no longer (or possibly never) - produced. Occasionally there are special features of newer terminals - which are awkward or impossible to represent by reusing the predefined - capabilities. - - <EM>ncurses</EM> addresses this limitation by allowing user-defined - capabilities. The <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> programs provide the <STRONG>-x</STRONG> option for - this purpose. When <STRONG>-x</STRONG> is set, <STRONG>tic</STRONG> treats unknown capabilities as user- - defined. That is, if <STRONG>tic</STRONG> encounters a capability name which it does - not recognize, it infers its type (Boolean, number or string) from the - syntax and makes an extended table entry for that capability. The - <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG> function makes this information conditionally - available to applications. The <EM>ncurses</EM> library provides the data - leaving most of the behavior to applications: - - <STRONG>o</STRONG> User-defined capability strings whose name begins with "k" are - treated as function keys. - - <STRONG>o</STRONG> The types (Boolean, number, string) determined by <STRONG>tic</STRONG> can be - inferred by successful calls on <STRONG>tigetflag</STRONG>, etc. + The preceding section listed the <EM>standard</EM> capabilities. Some are + esoteric, supporting functionality that terminal emulators do not + implement, or may never have been realized in manufactured hardware. + Occasionally, emulators have special features that are awkward or + impossible to represent via standard capabilities. + + <EM>ncurses</EM> addresses this limitation by allowing user-defined + capabilities. The <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> programs provide an <STRONG>-x</STRONG> option for + this purpose. When <STRONG>-x</STRONG> is used, <STRONG>tic</STRONG> treats unknown capabilities as + user-defined. That is, if <STRONG>tic</STRONG> encounters a capability name that it + does not recognize, the program infers the capability's type (Boolean, + numeric, or string) from the syntax of the capability value and makes + an extended table entry for that capability. <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG> + makes this information conditionally available to applications. + <EM>ncurses</EM> library functions supply callers with capability data, the + interpretation of which is mostly up to the application. + + <STRONG>o</STRONG> <EM>ncurses</EM> treats user-defined string capabilities whose names begin + with "k" as function keys. + + <STRONG>o</STRONG> Capability types (Boolean, numeric, or string) determined by <STRONG>tic</STRONG> + can be inferred by successful <STRONG><A HREF="curs_terminfo.3x.html">tigetflag(3x)</A></STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">tigetnum(3x)</A></STRONG>, and + <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> calls. <STRONG>o</STRONG> If the capability name happens to be two characters, the capability is also available through the termcap interface. - While termcap is said to be extensible because it does not use a - predefined set of capabilities, in practice it has been limited to the - capabilities defined by terminfo implementations. As a rule, user- - defined capabilities intended for use by termcap applications should be - limited to Booleans and numbers to avoid running past the 1023 byte - limit assumed by termcap implementations and their applications. In - particular, providing extended sets of function keys (past the 60 - numbered keys and the handful of special named keys) is best done using - the longer names available using terminfo. + While <EM>termcap</EM> is said to be extensible because it mandates no + capabilities, in practice it has been limited to those defined by <EM>term-</EM> + <EM>info</EM> implementations. As a rule, employ only user-defined capabilities + of Boolean and numeric type with <EM>termcap</EM> applications to avoid + overrunning the 1023 byte limit assumed by <EM>termcap</EM> implementations and + their applications. Specifically, support for extended sets of + function keys (past the 60 numbered keys and the handful of special + named keys) is better achieved with longer names available via <EM>term-</EM> + <EM>info</EM>. The <EM>ncurses</EM> library uses a few of these user-defined capabilities, as - described in <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>. Other user-defined capabilities (including - function keys) are described in the terminal database, in the section - on <EM>NCURSES</EM> <EM>USER-DEFINABLE</EM> <EM>CAPABILITIES</EM> + described in <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>. For other user-defined capabilities, + including function keys, consult the source form of the terminal + database, <EM>terminfo.src</EM>, under the heading "NCURSES USER-DEFINABLE + CAPABILITIES". </PRE><H3><a name="h3-A-Sample-Entry">A Sample Entry</a></H3><PRE> - The following entry, describing an ANSI-standard terminal, is - representative of what a <STRONG>terminfo</STRONG> entry for a modern terminal typically - looks like. + The following entry, describing an ANSI X3.64- (or ECMA-48-) -standard + terminal (henceforth "ANSI-standard" for brevity), is representative of + what a <EM>terminfo</EM> entry for a modern terminal typically looks like. ansi|ansi/pc-term compatible with color, am, mc5i, mir, msgr, @@ -1016,7 +1005,7 @@ <STRONG>o</STRONG> numeric capabilities giving the size of the terminal or the size of particular delays, and - <STRONG>o</STRONG> string capabilities, which give a sequence which can be used to + <STRONG>o</STRONG> string capabilities, which give a sequence which can be used to perform particular terminal operations. @@ -1027,15 +1016,15 @@ <STRONG>am</STRONG>. Hence the description of ansi includes <STRONG>am</STRONG>. Numeric capabilities are followed by the character "#" and then a positive value. Thus <STRONG>cols</STRONG>, which indicates the number of columns the terminal has, gives the - value "80" for ansi. Values for numeric capabilities may be specified - in decimal, octal, or hexadecimal, using the C programming language + value "80" for ansi. Values for numeric capabilities may be specified + in decimal, octal, or hexadecimal, using the C programming language conventions (e.g., 255, 0377 and 0xff or 0xFF). - Finally, string valued capabilities, such as <STRONG>el</STRONG> (clear to end of line - sequence) are given by the two-character code, an "=", and then a + Finally, string valued capabilities, such as <STRONG>el</STRONG> (clear to end of line + sequence) are given by the two-character code, an "=", and then a string ending at the next following ",". - A number of escape sequences are provided in the string valued + A number of escape sequences are provided in the string valued capabilities for easy encoding of characters there: <STRONG>o</STRONG> Both <STRONG>\E</STRONG> and <STRONG>\e</STRONG> map to an ESCAPE character, @@ -1055,8 +1044,8 @@ X/Open Curses does not say what "appropriate <EM>x</EM>" might be. In practice, that is a printable ASCII graphic character. The special case "^?" is interpreted as DEL (127). In all other cases, the character value is - AND'd with 0x1f, mapping to ASCII control codes in the range 0 through - 31. + logically "and"-ed with 0x1f, mapping to ASCII control codes in the + range 0 through 31. Other escapes include @@ -1071,28 +1060,28 @@ <STRONG>o</STRONG> and <STRONG>\0</STRONG> for null. <STRONG>\0</STRONG> will produce \200, which does not terminate a string but behaves - as a null character on most terminals, providing CS7 is specified. + as a null character on most terminals, providing CS7 is specified. See <STRONG>stty(1)</STRONG>. - The reason for this quirk is to maintain binary compatibility of - the compiled terminfo files with other implementations, e.g., the - SVr4 systems, which document this. Compiled terminfo files use - null-terminated strings, with no lengths. Modifying this would - require a new binary format, which would not work with other + The reason for this quirk is to maintain binary compatibility of + the compiled terminfo files with other implementations, e.g., the + SVr4 systems, which document this. Compiled terminfo files use + null-terminated strings, with no lengths. Modifying this would + require a new binary format, which would not work with other implementations. Finally, characters may be given as three octal digits after a <STRONG>\</STRONG>. - A delay in milliseconds may appear anywhere in a string capability, - enclosed in $<..> brackets, as in <STRONG>el</STRONG>=\EK$<5>, and padding characters + A delay in milliseconds may appear anywhere in a string capability, + enclosed in $<..> brackets, as in <STRONG>el</STRONG>=\EK$<5>, and padding characters are supplied by <STRONG><A HREF="curs_terminfo.3x.html">tputs(3x)</A></STRONG> to provide this delay. - <STRONG>o</STRONG> The delay must be a number with at most one decimal place of + <STRONG>o</STRONG> The delay must be a number with at most one decimal place of precision; it may be followed by suffixes "*" or "/" or both. - <STRONG>o</STRONG> A "*" indicates that the padding required is proportional to the - number of lines affected by the operation, and the amount given is - the per-affected-unit padding required. (In the case of insert + <STRONG>o</STRONG> A "*" indicates that the padding required is proportional to the + number of lines affected by the operation, and the amount given is + the per-affected-unit padding required. (In the case of insert character, the factor is still the number of <EM>lines</EM> affected.) Normally, padding is advisory if the device has the <STRONG>xon</STRONG> capability; @@ -1102,37 +1091,37 @@ delay of the given number of milliseconds even on devices for which <STRONG>xon</STRONG> is present to indicate flow control. - Sometimes individual capabilities must be commented out. To do this, - put a period before the capability name. For example, see the second + Sometimes individual capabilities must be commented out. To do this, + put a period before the capability name. For example, see the second <STRONG>ind</STRONG> in the example above. </PRE><H3><a name="h3-Fetching-Compiled-Descriptions">Fetching Compiled Descriptions</a></H3><PRE> - Terminal descriptions in <EM>ncurses</EM> are stored in terminal databases. - These databases, which are found by their pathname, may be configured + Terminal descriptions in <EM>ncurses</EM> are stored in terminal databases. + These databases, which are found by their pathname, may be configured either as directory trees or hashed databases (see <STRONG><A HREF="term.5.html">term(5)</A></STRONG>), - The library uses a compiled-in list of pathnames, which can be + The library uses a compiled-in list of pathnames, which can be overridden by environment variables. Before starting to search, - <EM>ncurses</EM> checks the search list, eliminating duplicates and pathnames - where no terminal database is found. The <EM>ncurses</EM> library reads the + <EM>ncurses</EM> checks the search list, eliminating duplicates and pathnames + where no terminal database is found. The <EM>ncurses</EM> library reads the first description which passes its consistency checks. - <STRONG>o</STRONG> The environment variable <STRONG>TERMINFO</STRONG> is checked first, for a terminal + <STRONG>o</STRONG> The environment variable <STRONG>TERMINFO</STRONG> is checked first, for a terminal database containing the terminal description. <STRONG>o</STRONG> Next, <EM>ncurses</EM> looks in <EM>$HOME/.terminfo</EM> for a compiled description. - This is an optional feature which may be omitted entirely from the + This is an optional feature which may be omitted entirely from the library, or limited to prevent accidental use by privileged applications. - <STRONG>o</STRONG> Next, if the environment variable <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> is set, <EM>ncurses</EM> - interprets the contents of that variable as a list of colon- + <STRONG>o</STRONG> Next, if the environment variable <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> is set, <EM>ncurses</EM> + interprets the contents of that variable as a list of colon- separated pathnames of terminal databases to be searched. - An empty pathname (i.e., if the variable begins or ends with a - colon, or contains adjacent colons) is interpreted as the system + An empty pathname (i.e., if the variable begins or ends with a + colon, or contains adjacent colons) is interpreted as the system location <EM>/usr/share/terminfo</EM>. <STRONG>o</STRONG> Finally, <EM>ncurses</EM> searches these compiled-in locations: @@ -1161,8 +1150,8 @@ effective way to prepare a terminal description is by imitating the description of a similar terminal in <EM>terminfo</EM> and to build up a description gradually, using partial descriptions with <EM>vi</EM> or some other - screen-oriented program to check that they are correct. Be aware that - a very unusual terminal may expose deficiencies in the ability of the + screen-oriented program to check that they are correct. Be aware that + a very unusual terminal may expose deficiencies in the ability of the <EM>terminfo</EM> file to describe it or bugs in the screen-handling code of the test program. @@ -1182,13 +1171,13 @@ can clear its screen, leaving the cursor in the home position, then this is given by the <STRONG>clear</STRONG> string capability. If the terminal overstrikes (rather than clearing a position when a character is struck - over) then it should have the <STRONG>os</STRONG> capability. If the terminal is a + over) then it should have the <STRONG>os</STRONG> capability. If the terminal is a printing terminal, with no soft copy unit, give it both <STRONG>hc</STRONG> and <STRONG>os</STRONG>. (<STRONG>os</STRONG> applies to storage scope terminals, such as TEKTRONIX 4010 series, as well as hard copy and APL terminals.) If there is a code to move the - cursor to the left edge of the current row, give this as <STRONG>cr</STRONG>. (Normally - this will be carriage return, control/M.) If there is a code to - produce an audible signal (bell, beep, etc) give this as <STRONG>bel</STRONG>. + cursor to the left edge of the current line, give this as <STRONG>cr</STRONG>. + (Normally this will be carriage return, control/M.) If there is a code + to produce an audible signal (bell, beep, etc) give this as <STRONG>bel</STRONG>. If there is a code to move the cursor one position to the left (such as backspace) that capability should be given as <STRONG>cub1</STRONG>. Similarly, codes @@ -1198,7 +1187,7 @@ space would erase the character moved over. A very important point here is that the local cursor motions encoded in - <EM>terminfo</EM> are undefined at the left and top edges of a CRT terminal. + <EM>terminfo</EM> are undefined at the left and top edges of a CRT terminal. Programs should never attempt to backspace around the left edge, unless <STRONG>bw</STRONG> is given, and never attempt to go up locally off the top. In order to scroll text up, a program will go to the bottom left corner of the @@ -1208,17 +1197,17 @@ screen and sends the <STRONG>ri</STRONG> (reverse index) string. The strings <STRONG>ind</STRONG> and <STRONG>ri</STRONG> are undefined when not on their respective corners of the screen. - Parameterized versions of the scrolling sequences are <STRONG>indn</STRONG> and <STRONG>rin</STRONG> - which have the same semantics as <STRONG>ind</STRONG> and <STRONG>ri</STRONG> except that they take one - parameter, and scroll that many lines. They are also undefined except + Parameterized versions of the scrolling sequences are <STRONG>indn</STRONG> and <STRONG>rin</STRONG> + which have the same semantics as <STRONG>ind</STRONG> and <STRONG>ri</STRONG> except that they take one + parameter, and scroll that many lines. They are also undefined except at the appropriate edge of the screen. - The <STRONG>am</STRONG> capability tells whether the cursor sticks at the right edge of - the screen when text is output, but this does not necessarily apply to - a <STRONG>cuf1</STRONG> from the last column. The only local motion which is defined - from the left edge is if <STRONG>bw</STRONG> is given, then a <STRONG>cub1</STRONG> from the left edge - will move to the right edge of the previous row. If <STRONG>bw</STRONG> is not given, - the effect is undefined. This is useful for drawing a box around the + The <STRONG>am</STRONG> capability tells whether the cursor sticks at the right edge of + the screen when text is output, but this does not necessarily apply to + a <STRONG>cuf1</STRONG> from the last column. The only local motion which is defined + from the left edge is if <STRONG>bw</STRONG> is given, then a <STRONG>cub1</STRONG> from the left edge + will move to the right edge of the previous line. If <STRONG>bw</STRONG> is not given, + the effect is undefined. This is useful for drawing a box around the edge of the screen, for example. If the terminal has switch selectable automatic margins, the <EM>terminfo</EM> file usually assumes that this is on; i.e., <STRONG>am</STRONG>. If the terminal has a command which moves to the first @@ -1244,17 +1233,17 @@ Cursor addressing and other strings requiring parameters in the terminal are described by a parameterized string capability, with <EM>printf</EM>-like escapes such as <EM>%x</EM> in it. For example, to address the - cursor, the <STRONG>cup</STRONG> capability is given, using two parameters: the row and - column to address to. (Rows and columns are numbered from zero and - refer to the physical screen visible to the user, not to any unseen - memory.) If the terminal has memory relative cursor addressing, that + cursor, the <STRONG>cup</STRONG> capability is given, using two parameters: the line and + column to address to. (Lines and columns are numbered from zero and + refer to the physical screen visible to the user, not to any unseen + memory.) If the terminal has memory relative cursor addressing, that can be indicated by <STRONG>mrcup</STRONG>. - The parameter mechanism uses a stack and special <STRONG>%</STRONG> codes to manipulate - it. Typically a sequence will push one of the parameters onto the - stack and then print it in some format. Print (e.g., "%d") is a - special case. Other operations, including "%t" pop their operand from - the stack. It is noted that more complex operations are often + The parameter mechanism uses a stack and special <STRONG>%</STRONG> codes to manipulate + it. Typically a sequence will push one of the parameters onto the + stack and then print it in some format. Print (e.g., "%d") is a + special case. Other operations, including "%t" pop their operand from + the stack. It is noted that more complex operations are often necessary, e.g., in the <STRONG>sgr</STRONG> string. The <STRONG>%</STRONG> encodings have the following meanings: @@ -1262,7 +1251,7 @@ <STRONG>%%</STRONG> outputs "%" <STRONG>%</STRONG><EM>[[</EM>:<EM>]flags][width[.precision]][</EM><STRONG>doxXs</STRONG><EM>]</EM> - as in <STRONG>printf(3)</STRONG>, flags are <EM>[-+#]</EM> and <EM>space</EM>. Use a ":" to allow + as in <STRONG>printf(3)</STRONG>, flags are <EM>[-+#]</EM> and <EM>space</EM>. Use a ":" to allow the next character to be a "-" flag, avoiding interpreting "%-" as an operator. @@ -1287,7 +1276,7 @@ The terms "static" and "dynamic" are misleading. Historically, these are simply two different sets of variables, whose values are - not reset between calls to <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>. However, that fact is not + not reset between calls to <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG>. However, that fact is not documented in other implementations. Relying on it will adversely impact portability to other implementations: @@ -1332,13 +1321,14 @@ arithmetic (%m is <EM>mod</EM>): <EM>push(pop()</EM> <EM>op</EM> <EM>pop())</EM> <STRONG>%&</STRONG>, <STRONG>%|</STRONG>, <STRONG>%^</STRONG> - bit operations (AND, OR and exclusive-OR): <EM>push(pop()</EM> <EM>op</EM> <EM>pop())</EM> + bit operations ("and", "or" and exclusive "or"): <EM>push(pop()</EM> <EM>op</EM> + <EM>pop())</EM> <STRONG>%=</STRONG>, <STRONG>%></STRONG>, <STRONG>%<</STRONG> logical operations: <EM>push(pop()</EM> <EM>op</EM> <EM>pop())</EM> <STRONG>%A</STRONG>, <STRONG>%O</STRONG> - logical AND and OR operations (for conditionals) + logical "and" and "or" operations (for conditionals) <STRONG>%!</STRONG>, <STRONG>%~</STRONG> unary operations (logical and bit complement): <EM>push(op</EM> <EM>pop())</EM> @@ -1347,8 +1337,8 @@ <STRONG>%?</STRONG> <EM>expr</EM> <STRONG>%t</STRONG> <EM>thenpart</EM> <STRONG>%e</STRONG> <EM>elsepart</EM> <STRONG>%;</STRONG> This forms an if-then-else. The <STRONG>%e</STRONG> <EM>elsepart</EM> is optional. Usually - the <STRONG>%?</STRONG> <EM>expr</EM> part pushes a value onto the stack, and <STRONG>%t</STRONG> pops it - from the stack, testing if it is nonzero (true). If it is zero + the <STRONG>%?</STRONG> <EM>expr</EM> part pushes a value onto the stack, and <STRONG>%t</STRONG> pops it + from the stack, testing if it is nonzero (true). If it is zero (false), control passes to the <STRONG>%e</STRONG> (else) part. It is possible to form else-if's a la Algol 68: @@ -1356,7 +1346,7 @@ where ci are conditions, bi are bodies. - Use the <STRONG>-f</STRONG> option of <STRONG>tic</STRONG> or <STRONG>infocmp</STRONG> to see the structure of if- + Use the <STRONG>-f</STRONG> option of <STRONG>tic</STRONG> or <STRONG>infocmp</STRONG> to see the structure of if- then-else's. Some strings, e.g., <STRONG>sgr</STRONG> can be very complicated when written on one line. The <STRONG>-f</STRONG> option splits the string into lines with the parts indented. @@ -1365,25 +1355,25 @@ order. That is, to get x-5 one would use "%gx%{5}%-". <STRONG>%P</STRONG> and <STRONG>%g</STRONG> variables are persistent across escape-string evaluations. - Consider the HP2645, which, to get to row 3 and column 12, needs to be - sent \E&a12c03Y padded for 6 milliseconds. The order of the rows and - columns is inverted here, and the row and column are printed as two + Consider the HP2645, which, to get to line 3 and column 12, needs to be + sent \E&a12c03Y padded for 6 milliseconds. The order of the lines and + columns is inverted here, and the lines and column are printed as two digits. The corresponding terminal description is expressed thus: cup=\E&a%p2%dc%p1%dY$<6>, - The Microterm ACT-IV needs the current row and column sent preceded by - a <STRONG>^T</STRONG>, with the row and column simply encoded in binary, + The Microterm ACT-IV needs the current line and column sent preceded by + a <STRONG>^T</STRONG>, with the line and column simply encoded in binary, cup=^T%p1%c%p2%c Terminals which use "%c" need to be able to backspace the cursor (<STRONG>cub1</STRONG>), and to move the cursor up one line on the screen (<STRONG>cuu1</STRONG>). This is necessary because it is not always safe to transmit <STRONG>\n</STRONG> <STRONG>^D</STRONG> and <STRONG>\r</STRONG>, as - the system may change or discard them. (The library routines dealing - with terminfo set tty modes so that tabs are never expanded, so \t is + the system may change or discard them. (The library routines dealing + with terminfo set tty modes so that tabs are never expanded, so \t is safe to send. This turns out to be essential for the Ann Arbor 4080.) - A final example is the LSI ADM-3a, which uses row and column offset by - a blank character, thus + A final example is the LSI ADM-3A, which uses line and column offset by + a space, thus cup=\E=%p1%' '%+%c%p2%' '%+%c After sending "\E=", this pushes the first parameter, pushes the ASCII @@ -1404,8 +1394,8 @@ corner of the screen, not of memory. (Thus, the \EH sequence on HP terminals cannot be used for <STRONG>home</STRONG>.) - If the terminal has row or column absolute cursor addressing, these can - be given as single parameter capabilities <STRONG>hpa</STRONG> (horizontal position + If the terminal has line or column absolute cursor addressing, these + can be given as single parameter capabilities <STRONG>hpa</STRONG> (horizontal position absolute) and <STRONG>vpa</STRONG> (vertical position absolute). Sometimes these are shorter than the more general two parameter sequence (as with the hp2645) and can be used in preference to <STRONG>cup</STRONG>. If there are @@ -1416,10 +1406,10 @@ If the terminal needs to be in a special mode when running a program that uses these capabilities, the codes to enter and exit this mode can - be given as <STRONG>smcup</STRONG> and <STRONG>rmcup</STRONG>. This arises, for example, from terminals - like the Concept with more than one page of memory. If the terminal - has only memory relative cursor addressing and not screen relative - cursor addressing, a one screen-sized window must be fixed into the + be given as <STRONG>smcup</STRONG> and <STRONG>rmcup</STRONG>. This arises, for example, from terminals + like the Concept with more than one page of memory. If the terminal + has only memory relative cursor addressing and not screen relative + cursor addressing, a one screen-sized window must be fixed into the terminal for cursor addressing to work properly. This is also used for the TEKTRONIX 4025, where <STRONG>smcup</STRONG> sets the command character to be the one used by terminfo. If the <STRONG>smcup</STRONG> sequence will not restore the @@ -1433,7 +1423,7 @@ were intended for use with printers. <STRONG>o</STRONG> The two terminal capabilities assume that the terminal may have the - capability of setting the left and/or right margin at the current + capability of setting the left and/or right margin at the current cursor column position. <STRONG>o</STRONG> The printer capabilities assume that the printer may have two types @@ -1442,22 +1432,22 @@ <STRONG>o</STRONG> the ability to set a top and/or bottom margin using the current line position, and - <STRONG>o</STRONG> parameterized capabilities for setting the top, bottom, left, - right margins given the number of rows or columns. + <STRONG>o</STRONG> parameterized capabilities for setting the top, bottom, left, + right margins given the number of lines or columns. - In practice, the categorization into "terminal" and "printer" is not + In practice, the categorization into "terminal" and "printer" is not suitable: - <STRONG>o</STRONG> The AT&T SVr4 terminal database uses <STRONG>smgl</STRONG> four times, for AT&T + <STRONG>o</STRONG> The AT&T SVr4 terminal database uses <STRONG>smgl</STRONG> four times, for AT&T hardware. - Three of the four are printers. They lack the ability to set + Three of the four are printers. They lack the ability to set left/right margins by specifying the column. - <STRONG>o</STRONG> Other (non-AT&T) terminals may support margins but using different + <STRONG>o</STRONG> Other (non-AT&T) terminals may support margins but using different assumptions from AT&T. - For instance, the DEC VT420 supports left/right margins, but only + For instance, the DEC VT420 supports left/right margins, but only using a column parameter. As an added complication, the VT420 uses two settings to fully enable left/right margins (left/right margin mode, and origin mode). The former enables the margins, which @@ -1466,7 +1456,7 @@ <STRONG>o</STRONG> Both DEC VT420 left/right margins are set with a single control sequence. If either is omitted, the corresponding margin is set to - the left or right edge of the display (rather than leaving the + the left or right edge of the display (rather than leaving the margin unmodified). These are the margin-related capabilities: @@ -1484,15 +1474,15 @@ <STRONG>smglr</STRONG> Set both left and right margins to <EM>L</EM> and <EM>R</EM> <STRONG>smgtb</STRONG> Set both top and bottom margins to <EM>T</EM> and <EM>B</EM> - When writing an application that uses these string capabilities, the - pairs should be first checked to see if each capability in the pair is + When writing an application that uses these string capabilities, the + pairs should be first checked to see if each capability in the pair is set or only one is set: - <STRONG>o</STRONG> If both <STRONG>smglp</STRONG> and <STRONG>smgrp</STRONG> are set, each is used with a single - argument, <EM>N</EM>, that gives the column number of the left and right + <STRONG>o</STRONG> If both <STRONG>smglp</STRONG> and <STRONG>smgrp</STRONG> are set, each is used with a single + argument, <EM>N</EM>, that gives the column number of the left and right margin, respectively. - <STRONG>o</STRONG> If both <STRONG>smgtp</STRONG> and <STRONG>smgbp</STRONG> are set, each is used to set the top and + <STRONG>o</STRONG> If both <STRONG>smgtp</STRONG> and <STRONG>smgbp</STRONG> are set, each is used to set the top and bottom margin, respectively: <STRONG>o</STRONG> <STRONG>smgtp</STRONG> is used with a single argument, <EM>N</EM>, the line number of the @@ -1500,12 +1490,12 @@ <STRONG>o</STRONG> <STRONG>smgbp</STRONG> is used with two arguments, <EM>N</EM> and <EM>M</EM>, that give the line number of the bottom margin, the first counting from the top of - the page and the second counting from the bottom. This - accommodates the two styles of specifying the bottom margin in + the page and the second counting from the bottom. This + accommodates the two styles of specifying the bottom margin in different manufacturers' printers. - When designing a terminfo entry for a printer that has a settable - bottom margin, only the first or second argument should be used, + When designing a terminfo entry for a printer that has a settable + bottom margin, only the first or second argument should be used, depending on the printer. When developing an application that uses <STRONG>smgbp</STRONG> to set the bottom margin, both arguments must be given. @@ -1515,8 +1505,8 @@ arguments, the column number of the left and right margins, in that order. - <STRONG>o</STRONG> Likewise, if only one of <STRONG>smgtp</STRONG> and <STRONG>smgbp</STRONG> is set, then it is used - with two arguments that give the top and bottom margins, in that + <STRONG>o</STRONG> Likewise, if only one of <STRONG>smgtp</STRONG> and <STRONG>smgbp</STRONG> is set, then it is used + with two arguments that give the top and bottom margins, in that order, counting from the top of the page. When designing a terminfo entry for a printer that requires setting @@ -1527,22 +1517,22 @@ Except for very old terminal descriptions, e.g., those developed for SVr4, the scheme just described should be considered obsolete. An improved set of capabilities was added late in the SVr4 releases (<STRONG>smglr</STRONG> - and <STRONG>smgtb</STRONG>), which explicitly use two parameters for setting the + and <STRONG>smgtb</STRONG>), which explicitly use two parameters for setting the left/right or top/bottom margins. When setting margins, the line- and column-values are zero-based. - The <STRONG>mgc</STRONG> string capability should be defined. Applications such as + The <STRONG>mgc</STRONG> string capability should be defined. Applications such as <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG> rely upon this to reset all margins. </PRE><H3><a name="h3-Area-Clears">Area Clears</a></H3><PRE> - If the terminal can clear from the current position to the end of the - line, leaving the cursor where it is, this should be given as <STRONG>el</STRONG>. If - the terminal can clear from the beginning of the line to the current - position inclusive, leaving the cursor where it is, this should be - given as <STRONG>el1</STRONG>. If the terminal can clear from the current position to - the end of the display, then this should be given as <STRONG>ed</STRONG>. <STRONG>Ed</STRONG> is only + If the terminal can clear from the current position to the end of the + line, leaving the cursor where it is, this should be given as <STRONG>el</STRONG>. If + the terminal can clear from the beginning of the line to the current + position inclusive, leaving the cursor where it is, this should be + given as <STRONG>el1</STRONG>. If the terminal can clear from the current position to + the end of the display, then this should be given as <STRONG>ed</STRONG>. <STRONG>Ed</STRONG> is only defined from the first column of a line. (Thus, it can be simulated by a request to delete a large number of lines, if a true <STRONG>ed</STRONG> is not available.) @@ -1563,8 +1553,8 @@ takes two parameters: the top and bottom lines of the scrolling region. The cursor position is, alas, undefined after using this command. - It is possible to get the effect of insert or delete line using <STRONG>csr</STRONG> on - a properly chosen region; the <STRONG>sc</STRONG> and <STRONG>rc</STRONG> (save and restore cursor) + It is possible to get the effect of insert or delete line using <STRONG>csr</STRONG> on + a properly chosen region; the <STRONG>sc</STRONG> and <STRONG>rc</STRONG> (save and restore cursor) commands may be useful for ensuring that your synthesized insert/delete string does not move the cursor. (Note that the <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> library does this synthesis automatically, so you need not compose @@ -1587,13 +1577,13 @@ off the bottom of the region by the <STRONG>ri</STRONG> re-appears, then scrolling is non-destructive. System V and X/Open Curses expect that <STRONG>ind</STRONG>, <STRONG>ri</STRONG>, <STRONG>indn</STRONG>, and <STRONG>rin</STRONG> will simulate destructive scrolling; their documentation - cautions you not to define <STRONG>csr</STRONG> unless this is true. This <STRONG>curses</STRONG> - implementation is more liberal and will do explicit erases after + cautions you not to define <STRONG>csr</STRONG> unless this is true. This <STRONG>curses</STRONG> + implementation is more liberal and will do explicit erases after scrolling if <STRONG>ndsrc</STRONG> is defined. - If the terminal has the ability to define a window as part of memory, - which all commands affect, it should be given as the parameterized - string <STRONG>wind</STRONG>. The four parameters are the starting and ending lines in + If the terminal has the ability to define a window as part of memory, + which all commands affect, it should be given as the parameterized + string <STRONG>wind</STRONG>. The four parameters are the starting and ending lines in memory and the starting and ending columns in memory, in that order. If the terminal can retain display memory above, then the <STRONG>da</STRONG> capability @@ -1634,49 +1624,49 @@ Terminfo can describe both terminals which have an insert mode, and terminals which send a simple sequence to open a blank position on the current line. Give as <STRONG>smir</STRONG> the sequence to get into insert mode. Give - as <STRONG>rmir</STRONG> the sequence to leave insert mode. Now give as <STRONG>ich1</STRONG> any - sequence needed to be sent just before sending the character to be - inserted. Most terminals with a true insert mode will not give <STRONG>ich1</STRONG>; - terminals which send a sequence to open a screen position should give + as <STRONG>rmir</STRONG> the sequence to leave insert mode. Now give as <STRONG>ich1</STRONG> any + sequence needed to be sent just before sending the character to be + inserted. Most terminals with a true insert mode will not give <STRONG>ich1</STRONG>; + terminals which send a sequence to open a screen position should give it here. - If your terminal has both, insert mode is usually preferable to <STRONG>ich1</STRONG>. - Technically, you should not give both unless the terminal actually - requires both to be used in combination. Accordingly, some non-curses - applications get confused if both are present; the symptom is doubled - characters in an update using insert. This requirement is now rare; - most <STRONG>ich</STRONG> sequences do not require previous smir, and most smir insert - modes do not require <STRONG>ich1</STRONG> before each character. Therefore, the new - <STRONG>curses</STRONG> actually assumes this is the case and uses either <STRONG>rmir</STRONG>/<STRONG>smir</STRONG> or - <STRONG>ich</STRONG>/<STRONG>ich1</STRONG> as appropriate (but not both). If you have to write an entry - to be used under new curses for a terminal old enough to need both, + If your terminal has both, insert mode is usually preferable to <STRONG>ich1</STRONG>. + Technically, you should not give both unless the terminal actually + requires both to be used in combination. Accordingly, some non-curses + applications get confused if both are present; the symptom is doubled + characters in an update using insert. This requirement is now rare; + most <STRONG>ich</STRONG> sequences do not require previous smir, and most smir insert + modes do not require <STRONG>ich1</STRONG> before each character. Therefore, the new + <STRONG>curses</STRONG> actually assumes this is the case and uses either <STRONG>rmir</STRONG>/<STRONG>smir</STRONG> or + <STRONG>ich</STRONG>/<STRONG>ich1</STRONG> as appropriate (but not both). If you have to write an entry + to be used under new curses for a terminal old enough to need both, include the <STRONG>rmir</STRONG>/<STRONG>smir</STRONG> sequences in <STRONG>ich1</STRONG>. If post insert padding is needed, give this as a number of milliseconds in <STRONG>ip</STRONG> (a string option). Any other sequence which may need to be sent after an insert of a single character may also be given in <STRONG>ip</STRONG>. If your - terminal needs both to be placed into an "insert mode" and a special - code to precede each inserted character, then both <STRONG>smir</STRONG>/<STRONG>rmir</STRONG> and <STRONG>ich1</STRONG> - can be given, and both will be used. The <STRONG>ich</STRONG> capability, with one + terminal needs both to be placed into an "insert mode" and a special + code to precede each inserted character, then both <STRONG>smir</STRONG>/<STRONG>rmir</STRONG> and <STRONG>ich1</STRONG> + can be given, and both will be used. The <STRONG>ich</STRONG> capability, with one parameter, <EM>n</EM>, will repeat the effects of <STRONG>ich1</STRONG> <EM>n</EM> times. - If padding is necessary between characters typed while not in insert + If padding is necessary between characters typed while not in insert mode, give this as a number of milliseconds padding in <STRONG>rmp</STRONG>. - It is occasionally necessary to move around while in insert mode to - delete characters on the same line (e.g., if there is a tab after the - insertion position). If your terminal allows motion while in insert - mode you can give the capability <STRONG>mir</STRONG> to speed up inserting in this - case. Omitting <STRONG>mir</STRONG> will affect only speed. Some terminals (notably - Datamedia's) must not have <STRONG>mir</STRONG> because of the way their insert mode + It is occasionally necessary to move around while in insert mode to + delete characters on the same line (e.g., if there is a tab after the + insertion position). If your terminal allows motion while in insert + mode you can give the capability <STRONG>mir</STRONG> to speed up inserting in this + case. Omitting <STRONG>mir</STRONG> will affect only speed. Some terminals (notably + Datamedia's) must not have <STRONG>mir</STRONG> because of the way their insert mode works. - Finally, you can specify <STRONG>dch1</STRONG> to delete a single character, <STRONG>dch</STRONG> with - one parameter, <EM>n</EM>, to delete <EM>n</EM>characters, and delete mode by giving <STRONG>smdc</STRONG> - and <STRONG>rmdc</STRONG> to enter and exit delete mode (any mode the terminal needs to - be placed in for <STRONG>dch1</STRONG> to work). + Finally, you can specify <STRONG>dch1</STRONG> to delete a single character, <STRONG>dch</STRONG> with + one parameter, <EM>n</EM>, to delete <EM>n</EM> characters, and delete mode by giving + <STRONG>smdc</STRONG> and <STRONG>rmdc</STRONG> to enter and exit delete mode (any mode the terminal + needs to be placed in for <STRONG>dch1</STRONG> to work). - A command to erase <EM>n</EM> characters (equivalent to outputting <EM>n</EM> blanks + A command to erase <EM>n</EM> characters (equivalent to outputting <EM>n</EM> blanks without moving the cursor) can be given as <STRONG>ech</STRONG> with one parameter. @@ -1704,8 +1694,8 @@ mode) and <STRONG>rmacs</STRONG> (exit alternate character set mode). Turning on any of these modes singly may or may not turn off other modes. - If there is a sequence to set arbitrary combinations of modes, this - should be given as <STRONG>sgr</STRONG> (set attributes), taking 9 parameters. Each + If there is a sequence to set arbitrary combinations of modes, this + should be given as <STRONG>sgr</STRONG> (set attributes), taking 9 parameters. Each parameter is either zero (0) or nonzero, as the corresponding attribute is on or off. The 9 parameters are, in order: standout, underline, reverse, blink, dim, bold, blank, protect, alternate character set. @@ -1765,30 +1755,30 @@ string. The only drawback to adding an sgr string is that termcap also assumes that sgr0 does not exit alternate character set mode. - Terminals with the "magic cookie" glitch (<STRONG>xmc</STRONG>) deposit special - "cookies" when they receive mode-setting sequences, which affect the - display algorithm rather than having extra bits for each character. - Some terminals, such as the HP 2621, automatically leave standout mode - when they move to a new line or the cursor is addressed. Programs - using standout mode should exit standout mode before moving the cursor - or sending a newline, unless the <STRONG>msgr</STRONG> capability, asserting that it is + Terminals with the "magic cookie" glitch (<STRONG>xmc</STRONG>) deposit special + "cookies" when they receive mode-setting sequences, which affect the + display algorithm rather than having extra bits for each character. + Some terminals, such as the HP 2621, automatically leave standout mode + when they move to a new line or the cursor is addressed. Programs + using standout mode should exit standout mode before moving the cursor + or sending a newline, unless the <STRONG>msgr</STRONG> capability, asserting that it is safe to move in standout mode, is present. - If the terminal has a way of flashing the screen to indicate an error - quietly (a bell replacement) then this can be given as <STRONG>flash</STRONG>; it must + If the terminal has a way of flashing the screen to indicate an error + quietly (a bell replacement) then this can be given as <STRONG>flash</STRONG>; it must not move the cursor. - If the cursor needs to be made more visible than normal when it is not + If the cursor needs to be made more visible than normal when it is not on the bottom line (to make, for example, a non-blinking underline into an easier to find block or blinking underline) give this sequence as <STRONG>cvvis</STRONG>. If there is a way to make the cursor completely invisible, give - that as <STRONG>civis</STRONG>. The capability <STRONG>cnorm</STRONG> should be given which undoes the + that as <STRONG>civis</STRONG>. The capability <STRONG>cnorm</STRONG> should be given which undoes the effects of both of these modes. - If your terminal correctly generates underlined characters (with no - special codes needed) even though it does not overstrike, then you - should give the capability <STRONG>ul</STRONG>. If a character overstriking another - leaves both characters on the screen, specify the capability <STRONG>os</STRONG>. If + If your terminal correctly generates underlined characters (with no + special codes needed) even though it does not overstrike, then you + should give the capability <STRONG>ul</STRONG>. If a character overstriking another + leaves both characters on the screen, specify the capability <STRONG>os</STRONG>. If overstrikes are erasable with a blank, then this should be indicated by giving <STRONG>eo</STRONG>. @@ -1797,12 +1787,12 @@ If the terminal has a keypad that transmits codes when the keys are pressed, this information can be given. Note that it is not possible to handle terminals where the keypad only works in local (this applies, - for example, to the unshifted HP 2621 keys). If the keypad can be set - to transmit or not transmit, give these codes as <STRONG>smkx</STRONG> and <STRONG>rmkx</STRONG>. + for example, to the unshifted HP 2621 keys). If the keypad can be set + to transmit or not transmit, give these codes as <STRONG>smkx</STRONG> and <STRONG>rmkx</STRONG>. Otherwise the keypad is assumed to always transmit. - The codes sent by the left arrow, right arrow, up arrow, down arrow, - and home keys can be given as <STRONG>kcub1,</STRONG> <STRONG>kcuf1,</STRONG> <STRONG>kcuu1,</STRONG> <STRONG>kcud1,</STRONG> and <STRONG>khome</STRONG> + The codes sent by the left arrow, right arrow, up arrow, down arrow, + and home keys can be given as <STRONG>kcub1,</STRONG> <STRONG>kcuf1,</STRONG> <STRONG>kcuu1,</STRONG> <STRONG>kcud1,</STRONG> and <STRONG>khome</STRONG> respectively. If there are function keys such as f0, f1, ..., f10, the codes they send can be given as <STRONG>kf0,</STRONG> <STRONG>kf1,</STRONG> <STRONG>...,</STRONG> <STRONG>kf10</STRONG>. If these keys have labels other than the default f0 through f10, the labels can be @@ -1850,8 +1840,8 @@ directional pad are needed. Strings to program function keys can be given as <STRONG>pfkey</STRONG>, <STRONG>pfloc</STRONG>, and <STRONG>pfx</STRONG>. - A string to program screen labels should be specified as <STRONG>pln</STRONG>. Each of - these strings takes two parameters: the function key number to program + A string to program screen labels should be specified as <STRONG>pln</STRONG>. Each of + these strings takes two parameters: the function key number to program (from 0 to 10) and the string to program it with. Function key numbers out of this range may program undefined keys in a terminal dependent manner. The difference between the capabilities is that <STRONG>pfkey</STRONG> causes @@ -1867,41 +1857,45 @@ </PRE><H3><a name="h3-Tabs-and-Initialization">Tabs and Initialization</a></H3><PRE> - A few capabilities are used only for tabs: + A few capabilities are used only to manage tab stops. - <STRONG>o</STRONG> If the terminal has hardware tabs, the command to advance to the - next tab stop can be given as <STRONG>ht</STRONG> (usually control/I). + <STRONG>o</STRONG> If the terminal has hardware tabs, specify the character sequence + that advances to the next tab stop as the value of the <STRONG>tab</STRONG> (<STRONG>ht</STRONG>) + string capability (usually Control+I). - <STRONG>o</STRONG> A "back-tab" command which moves leftward to the preceding tab stop - can be given as <STRONG>cbt</STRONG>. + <STRONG>o</STRONG> Specify a character sequence that retreats (moves leftward) to the + preceding tab stop as the value of the <STRONG>back_tab</STRONG> (<STRONG>cbt</STRONG>) string + capability. - By convention, if the teletype modes indicate that tabs are being - expanded by the computer rather than being sent to the terminal, - programs should not use <STRONG>ht</STRONG> or <STRONG>cbt</STRONG> even if they are present, since - the user may not have the tab stops properly set. + By convention, if the terminal modes are configured such that tabs + are expanded by the host rather than terminal, applications should + not employ the <STRONG>tab</STRONG> (<STRONG>ht</STRONG>) or <STRONG>back_tab</STRONG> (<STRONG>cbt</STRONG>) capabilities even if they + are present, since the user may not have the tab stops properly + set. - <STRONG>o</STRONG> If the terminal has hardware tabs which are initially set every <EM>n</EM> - spaces when the terminal is powered up, the numeric parameter <STRONG>it</STRONG> is - given, showing the number of spaces the tabs are set to. + <STRONG>o</STRONG> If the terminal has hardware tab stops that are set at every <EM>n</EM> + character cells when the terminal is powered up, specify <EM>n</EM> as the + value of the the numeric capability <STRONG>init_tabs</STRONG> (<STRONG>it</STRONG>). - The <STRONG>it</STRONG> capability is normally used by the <STRONG>tset</STRONG> command to determine - whether to set the mode for hardware tab expansion, and whether to - set the tab stops. If the terminal has tab stops that can be saved - in non-volatile memory, the terminfo description can assume that - they are properly set. + The <STRONG>tset</STRONG> and "<STRONG>tput</STRONG> <STRONG>init</STRONG>" commands interpret the presence of the + <STRONG>init_tabs</STRONG> (<STRONG>it</STRONG>) capability as implying that the terminal is + responsible for tab stop expansion as well as an instruction to set + the tab stops to its value. If the terminal has tab stops that can + be saved in non-volatile memory, its <EM>terminfo</EM> type description can + assume that they are properly set. Other capabilities include <STRONG>o</STRONG> <STRONG>is1</STRONG>, <STRONG>is2</STRONG>, and <STRONG>is3</STRONG>, initialization strings for the terminal, - <STRONG>o</STRONG> <STRONG>iprog</STRONG>, the path name of a program to be run to initialize the + <STRONG>o</STRONG> <STRONG>iprog</STRONG>, the path name of a program to be run to initialize the terminal, <STRONG>o</STRONG> and <STRONG>if</STRONG>, the name of a file containing long initialization strings. - These strings are expected to set the terminal into modes consistent - with the rest of the terminfo description. They are normally sent to - the terminal, by the <EM>init</EM> option of the <STRONG>tput</STRONG> program, each time the + These strings are expected to set the terminal into modes consistent + with the rest of the terminfo description. They are normally sent to + the terminal, by the <EM>init</EM> option of the <STRONG>tput</STRONG> program, each time the user logs in. They will be printed in the following order: run the program @@ -1925,30 +1919,30 @@ and finally output <STRONG>is3</STRONG>. - Most initialization is done with <STRONG>is2</STRONG>. Special terminal modes can be - set up without duplicating strings by putting the common sequences in + Most initialization is done with <STRONG>is2</STRONG>. Special terminal modes can be + set up without duplicating strings by putting the common sequences in <STRONG>is2</STRONG> and special cases in <STRONG>is1</STRONG> and <STRONG>is3</STRONG>. - A set of sequences that does a harder reset from a totally unknown + A set of sequences that does a harder reset from a totally unknown state can be given as <STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>, <STRONG>rf</STRONG> and <STRONG>rs3</STRONG>, analogous to <STRONG>is1</STRONG> <STRONG>,</STRONG> <STRONG>is2</STRONG> <STRONG>,</STRONG> <STRONG>if</STRONG> and <STRONG>is3</STRONG> respectively. These strings are output by <EM>reset</EM> option of <STRONG>tput</STRONG>, or by the <STRONG>reset</STRONG> program (an alias of <STRONG>tset</STRONG>), which is used when the terminal gets into a wedged state. Commands are normally placed in <STRONG>rs1</STRONG>, <STRONG>rs2</STRONG> <STRONG>rs3</STRONG> and <STRONG>rf</STRONG> only if they produce annoying effects on the screen and are not necessary when logging in. For example, the command to set - the vt100 into 80-column mode would normally be part of <STRONG>is2</STRONG>, but it - causes an annoying glitch of the screen and is not normally needed + the vt100 into 80-column mode would normally be part of <STRONG>is2</STRONG>, but it + causes an annoying glitch of the screen and is not normally needed since the terminal is usually already in 80-column mode. - The <STRONG>reset</STRONG> program writes strings including <STRONG>iprog</STRONG>, etc., in the same - order as the <EM>init</EM> program, using <STRONG>rs1</STRONG>, etc., instead of <STRONG>is1</STRONG>, etc. If - any of <STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>, <STRONG>rs3</STRONG>, or <STRONG>rf</STRONG> reset capability strings are missing, the - <STRONG>reset</STRONG> program falls back upon the corresponding initialization + The <STRONG>reset</STRONG> program writes strings including <STRONG>iprog</STRONG>, etc., in the same + order as the <EM>init</EM> program, using <STRONG>rs1</STRONG>, etc., instead of <STRONG>is1</STRONG>, etc. If + any of <STRONG>rs1</STRONG>, <STRONG>rs2</STRONG>, <STRONG>rs3</STRONG>, or <STRONG>rf</STRONG> reset capability strings are missing, the + <STRONG>reset</STRONG> program falls back upon the corresponding initialization capability string. - If there are commands to set and clear tab stops, they can be given as + If there are commands to set and clear tab stops, they can be given as <STRONG>tbc</STRONG> (clear all tab stops) and <STRONG>hts</STRONG> (set a tab stop in the current column - of every row). If a more complex sequence is needed to set the tabs + of every line). If a more complex sequence is needed to set the tabs than can be described by this, the sequence can be placed in <STRONG>is2</STRONG> or <STRONG>if</STRONG>. The <STRONG>tput</STRONG> <STRONG>reset</STRONG> command uses the same capability strings as the <STRONG>reset</STRONG> @@ -1961,11 +1955,11 @@ <STRONG>o</STRONG> Almost all hardware terminals (at least those which supported tabs) initialized those to every <EM>eight</EM> columns: - The only exception was the AT&T 2300 series, which set tabs to + The only exception was the AT&T 2300 series, which set tabs to every <EM>five</EM> columns. - <STRONG>o</STRONG> In particular, developers of the hardware terminals which are - commonly used as models for modern terminal emulators provided + <STRONG>o</STRONG> In particular, developers of the hardware terminals which are + commonly used as models for modern terminal emulators provided documentation demonstrating that <EM>eight</EM> columns were the standard. <STRONG>o</STRONG> Because of this, the terminal initialization programs <STRONG>tput</STRONG> and <STRONG>tset</STRONG> @@ -1981,36 +1975,36 @@ characters after certain cursor motions and screen changes. If the terminal uses xon/xoff handshaking for flow control (that is, it - automatically emits ^S back to the host when its input buffers are - close to full), set <STRONG>xon</STRONG>. This capability suppresses the emission of - padding. You can also set it for memory-mapped console devices + automatically emits ^S back to the host when its input buffers are + close to full), set <STRONG>xon</STRONG>. This capability suppresses the emission of + padding. You can also set it for memory-mapped console devices effectively that do not have a speed limit. Padding information should still be included so that routines can make better decisions about relative costs, but actual pad characters will not be transmitted. If <STRONG>pb</STRONG> (padding baud rate) is given, padding is suppressed at baud rates - below the value of <STRONG>pb</STRONG>. If the entry has no padding baud rate, then + below the value of <STRONG>pb</STRONG>. If the entry has no padding baud rate, then whether padding is emitted or not is completely controlled by <STRONG>xon</STRONG>. - If the terminal requires other than a null (zero) character as a pad, - then this can be given as <STRONG>pad</STRONG>. Only the first character of the <STRONG>pad</STRONG> + If the terminal requires other than a null (zero) character as a pad, + then this can be given as <STRONG>pad</STRONG>. Only the first character of the <STRONG>pad</STRONG> string is used. </PRE><H3><a name="h3-Status-Lines">Status Lines</a></H3><PRE> - Some terminals have an extra "status line" which is not normally used + Some terminals have an extra "status line" which is not normally used by software (and thus not counted in the terminal's <STRONG>lines</STRONG> capability). - The simplest case is a status line which is cursor-addressable but not + The simplest case is a status line which is cursor-addressable but not part of the main scrolling region on the screen; the Heathkit H19 has a status line of this kind, as would a 24-line VT100 with a 23-line scrolling region set up on initialization. This situation is indicated by the <STRONG>hs</STRONG> capability. - Some terminals with status lines need special sequences to access the - status line. These may be expressed as a string with single parameter - <STRONG>tsl</STRONG> which takes the cursor to a given zero-origin column on the status - line. The capability <STRONG>fsl</STRONG> must return to the main-screen cursor + Some terminals with status lines need special sequences to access the + status line. These may be expressed as a string with single parameter + <STRONG>tsl</STRONG> which takes the cursor to a given zero-origin column on the status + line. The capability <STRONG>fsl</STRONG> must return to the main-screen cursor positions before the last <STRONG>tsl</STRONG>. You may need to embed the string values of <STRONG>sc</STRONG> (save cursor) and <STRONG>rc</STRONG> (restore cursor) in <STRONG>tsl</STRONG> and <STRONG>fsl</STRONG> to accomplish this. @@ -2050,7 +2044,6 @@ <STRONG>ACS_BOARD</STRONG> 0x68 h <STRONG>#</STRONG> board of squares <STRONG>ACS_LANTERN</STRONG> 0x69 i <STRONG>#</STRONG> lantern symbol <STRONG>ACS_LRCORNER</STRONG> 0x6a j <STRONG>+</STRONG> lower right corner - <STRONG>ACS_URCORNER</STRONG> 0x6b k <STRONG>+</STRONG> upper right corner <STRONG>ACS_ULCORNER</STRONG> 0x6c l <STRONG>+</STRONG> upper left corner <STRONG>ACS_LLCORNER</STRONG> 0x6d m <STRONG>+</STRONG> lower left corner @@ -2089,43 +2082,48 @@ presumably they were used in the AT&T terminal: <EM>board</EM> <EM>of</EM> <EM>squares</EM> replaces the VT100 <EM>newline</EM> symbol, while <EM>lantern</EM> <EM>symbol</EM> replaces the VT100 <EM>vertical</EM> <EM>tab</EM> symbol. The other VT100 symbols for control - characters (<EM>horizontal</EM> <EM>tab</EM>, <EM>carriage</EM> <EM>return</EM> and <EM>line-feed</EM>) are not + characters (<EM>horizontal</EM> <EM>tab</EM>, <EM>carriage</EM> <EM>return</EM> and <EM>line-feed</EM>) are not (re)used in curses. - The best way to define a new device's graphics set is to add a column - to a copy of this table for your terminal, giving the character which - (when emitted between <STRONG>smacs</STRONG>/<STRONG>rmacs</STRONG> switches) will be rendered as the + The best way to define a new device's graphics set is to add a column + to a copy of this table for your terminal, giving the character which + (when emitted between <STRONG>smacs</STRONG>/<STRONG>rmacs</STRONG> switches) will be rendered as the corresponding graphic. Then read off the VT100/your terminal character pairs right to left in sequence; these become the ACSC string. </PRE><H3><a name="h3-Color-Handling">Color Handling</a></H3><PRE> - The curses library functions <STRONG>init_pair</STRONG> and <STRONG>init_color</STRONG> manipulate the - <EM>color</EM> <EM>pairs</EM> and <EM>color</EM> <EM>values</EM> discussed in this section (see - <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> for details on these and related functions). - - Most color terminals are either "Tektronix-like" or "HP-like": - - <STRONG>o</STRONG> Tektronix-like terminals have a predefined set of <EM>N</EM> colors (where <EM>N</EM> - is usually 8), and can set character-cell foreground and background - characters independently, mixing them into <EM>N</EM> * <EM>N</EM> color pairs. - - <STRONG>o</STRONG> On HP-like terminals, the user must set each color pair up - separately (foreground and background are not independently - settable). Up to <EM>M</EM> color pairs may be set up from 2*<EM>M</EM> different - colors. ANSI-compatible terminals are Tektronix-like. - - Some basic color capabilities are independent of the color method. The - numeric capabilities <STRONG>colors</STRONG> and <STRONG>pairs</STRONG> specify the maximum numbers of - colors and color pairs that can be displayed simultaneously. The <STRONG>op</STRONG> - (original pair) string resets foreground and background colors to their - default values for the terminal. The <STRONG>oc</STRONG> string resets all colors or - color pairs to their default values for the terminal. Some terminals + The <EM>curses</EM> library functions <STRONG>init_pair</STRONG> and <STRONG>init_color</STRONG> manipulate the + <EM>color</EM> <EM>pairs</EM> and <EM>colors</EM> (color values or indices, such as "1=red") + discussed in this section (see <STRONG><A HREF="curs_color.3x.html">curs_color(3x)</A></STRONG> for details on these and + related functions). + + Most color terminals are either "Tektronix-like" or "HP-like" in their + approach to color management. + + <STRONG>o</STRONG> <EM>Tektronix-like</EM> terminals define a set of <EM>n</EM> colors (where <EM>n</EM> is + usually 8), and can alter character-cell foreground and background + colors independently, mixing them into <EM>n</EM>x<EM>n</EM> color pairs. ANSI- + standard terminals are Tektronix-like. + + <STRONG>o</STRONG> On <EM>HP-like</EM> terminals, the user must set up each color pair + separately; foreground and background are not independently + alterable. Up to <EM>m</EM> color pairs may be configured from 2x<EM>m</EM> + different colors. + + Some basic color management capabilities are independent of the color + encoding method. The numeric capabilities <STRONG>max_colors</STRONG> (<STRONG>colors</STRONG>) and + <STRONG>max_pairs</STRONG> (<STRONG>pairs</STRONG>) specify the maximum numbers of colors and color pairs + that the device can display simultaneously. The <STRONG>orig_pair</STRONG> (<STRONG>op</STRONG>) + ("original pair") string capability resets foreground and background + colors to their default values for the terminal. The <STRONG>orig_colors</STRONG> (<STRONG>oc</STRONG>) + ("original colors") string capability resets all colors or color pairs + to their default values for the terminal. Some terminal types (including many PC terminal emulators) erase screen areas with the current background color rather than the power-up default background; - these should have the Boolean capability <STRONG>bce</STRONG>. + these should declare the Boolean capability <STRONG>back_color_erase</STRONG> (<STRONG>bce</STRONG>). - While the curses library works with <EM>color</EM> <EM>pairs</EM> (reflecting the + While the <EM>curses</EM> library works with <EM>color</EM> <EM>pairs</EM> (reflecting the inability of some devices to set foreground and background colors independently), there are separate capabilities for setting these features: @@ -2134,17 +2132,17 @@ Tektronix-type terminal, use <STRONG>setaf</STRONG> (set ANSI foreground) and <STRONG>setab</STRONG> (set ANSI background) or <STRONG>setf</STRONG> (set foreground) and <STRONG>setb</STRONG> (set background). These take one parameter, the color number. The SVr4 - documentation describes only <STRONG>setaf</STRONG>/<STRONG>setab</STRONG>; the XPG4 draft says that - "If the terminal supports ANSI escape sequences to set background - and foreground, they should be coded as <STRONG>setaf</STRONG> and <STRONG>setab</STRONG>, + documentation describes only <STRONG>setaf</STRONG>/<STRONG>setab</STRONG>; the XPG4 draft says that + "If the terminal supports ANSI escape sequences to set background + and foreground, they should be coded as <STRONG>setaf</STRONG> and <STRONG>setab</STRONG>, respectively. - <STRONG>o</STRONG> If the terminal supports other escape sequences to set background - and foreground, they should be coded as <STRONG>setf</STRONG> and <STRONG>setb</STRONG>, - respectively. The <STRONG>vidputs</STRONG> and the <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> functions use the + <STRONG>o</STRONG> If the terminal supports other escape sequences to set background + and foreground, they should be coded as <STRONG>setf</STRONG> and <STRONG>setb</STRONG>, + respectively. The <STRONG>vidputs</STRONG> and the <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG> functions use the <STRONG>setaf</STRONG> and <STRONG>setab</STRONG> capabilities if they are defined. - The <STRONG>setaf</STRONG>/<STRONG>setab</STRONG> and <STRONG>setf</STRONG>/<STRONG>setb</STRONG> capabilities take a single numeric + The <STRONG>setaf</STRONG>/<STRONG>setab</STRONG> and <STRONG>setf</STRONG>/<STRONG>setb</STRONG> capabilities take a single numeric argument each. Argument values 0-7 of <STRONG>setaf</STRONG>/<STRONG>setab</STRONG> are portably defined as follows (the middle column is the symbolic #define available in the header for the <STRONG>curses</STRONG> or <EM>ncurses</EM> libraries). The terminal hardware is @@ -2176,32 +2174,32 @@ yellow <STRONG>COLOR_YELLOW</STRONG> 6 max, max, 0 white <STRONG>COLOR_WHITE</STRONG> 7 max, max, max - It is important to not confuse the two sets of color capabilities; + It is important to not confuse the two sets of color capabilities; otherwise red/blue will be interchanged on the display. - On an HP-like terminal, use <STRONG>scp</STRONG> with a color pair number parameter to + On an HP-like terminal, use <STRONG>scp</STRONG> with a color pair number parameter to set which color pair is current. Some terminals allow the <EM>color</EM> <EM>values</EM> to be modified: - <STRONG>o</STRONG> On a Tektronix-like terminal, the capability <STRONG>ccc</STRONG> may be present to - indicate that colors can be modified. If so, the <STRONG>initc</STRONG> capability + <STRONG>o</STRONG> On a Tektronix-like terminal, the capability <STRONG>ccc</STRONG> may be present to + indicate that colors can be modified. If so, the <STRONG>initc</STRONG> capability will take a color number (0 to <STRONG>colors</STRONG> - 1)and three more parameters which describe the color. These three parameters default to being interpreted as RGB (Red, Green, Blue) values. If the Boolean capability <STRONG>hls</STRONG> is present, they are instead as HLS (Hue, Lightness, Saturation) indices. The ranges are terminal-dependent. - <STRONG>o</STRONG> On an HP-like terminal, <STRONG>initp</STRONG> may give a capability for changing a - color pair value. It will take seven parameters; a color pair - number (0 to <STRONG>max_pairs</STRONG> - 1), and two triples describing first - background and then foreground colors. These parameters must be - (Red, Green, Blue) or (Hue, Lightness, Saturation) depending on + <STRONG>o</STRONG> On an HP-like terminal, <STRONG>initp</STRONG> may give a capability for changing a + color pair value. It will take seven parameters; a color pair + number (0 to <STRONG>max_pairs</STRONG> - 1), and two triples describing first + background and then foreground colors. These parameters must be + (Red, Green, Blue) or (Hue, Lightness, Saturation) depending on <STRONG>hls</STRONG>. - On some color terminals, colors collide with highlights. You can - register these collisions with the <STRONG>ncv</STRONG> capability. This is a bit mask - of attributes not to be used when colors are enabled. The + On some color terminals, colors collide with highlights. You can + register these collisions with the <STRONG>ncv</STRONG> capability. This is a bit mask + of attributes not to be used when colors are enabled. The correspondence with the attributes understood by <STRONG>curses</STRONG> is as follows: <STRONG>Attribute</STRONG> <STRONG>Bit</STRONG> <STRONG>Decimal</STRONG> <STRONG>Set</STRONG> <STRONG>by</STRONG> @@ -2223,17 +2221,17 @@ <STRONG>A_VERTICAL</STRONG> 14 16384 <STRONG>sgr1</STRONG> <STRONG>A_ITALIC</STRONG> 15 32768 <STRONG>sitm</STRONG> - For example, on many IBM PC consoles, the underline attribute collides - with the foreground color blue and is not available in color mode. + For example, on many IBM PC consoles, the underline attribute collides + with the foreground color blue and is not available in color mode. These should have an <STRONG>ncv</STRONG> capability of 2. - SVr4 curses does nothing with <STRONG>ncv</STRONG>, <EM>ncurses</EM> recognizes it and optimizes + SVr4 curses does nothing with <STRONG>ncv</STRONG>, <EM>ncurses</EM> recognizes it and optimizes the output in favor of colors. </PRE><H3><a name="h3-Miscellaneous">Miscellaneous</a></H3><PRE> - If the terminal requires other than a null (zero) character as a pad, - then this can be given as pad. Only the first character of the pad + If the terminal requires other than a null (zero) character as a pad, + then this can be given as pad. Only the first character of the pad string is used. If the terminal does not have a pad character, specify npc. Note that <EM>ncurses</EM> implements the termcap-compatible <STRONG>PC</STRONG> variable; though the application may set this value to something other than a @@ -2246,17 +2244,17 @@ hard-copy terminal can eject to the next page (form feed), give this as <STRONG>ff</STRONG> (usually control/L). - If there is a command to repeat a given character a given number of - times (to save time transmitting a large number of identical - characters) this can be indicated with the parameterized string <STRONG>rep</STRONG>. - The first parameter is the character to be repeated and the second is + If there is a command to repeat a given character a given number of + times (to save time transmitting a large number of identical + characters) this can be indicated with the parameterized string <STRONG>rep</STRONG>. + The first parameter is the character to be repeated and the second is the number of times to repeat it. Thus, tparm(repeat_char, 'x', 10) is the same as "xxxxxxxxxx". If the terminal has a settable command character, such as the TEKTRONIX - 4025, this can be indicated with <STRONG>cmdch</STRONG>. A prototype command character - is chosen which is used in all capabilities. This character is given - in the <STRONG>cmdch</STRONG> capability to identify it. The following convention is + 4025, this can be indicated with <STRONG>cmdch</STRONG>. A prototype command character + is chosen which is used in all capabilities. This character is given + in the <STRONG>cmdch</STRONG> capability to identify it. The following convention is supported on some Unix systems: The environment is to be searched for a <STRONG>CC</STRONG> variable, and if found, all occurrences of the prototype character are replaced with the character in the environment variable. @@ -2269,9 +2267,9 @@ known.) If the terminal has a "meta key" which acts as a shift key, setting the - 8th bit of any character transmitted, this fact can be indicated with - <STRONG>km</STRONG>. Otherwise, software will assume that the 8th bit is parity and it - will usually be cleared. If strings exist to turn this "meta mode" on + 8th bit of any character transmitted, this fact can be indicated with + <STRONG>km</STRONG>. Otherwise, software will assume that the 8th bit is parity and it + will usually be cleared. If strings exist to turn this "meta mode" on and off, they can be given as <STRONG>smm</STRONG> and <STRONG>rmm</STRONG>. If the terminal has more lines of memory than will fit on the screen at @@ -2279,16 +2277,16 @@ of <STRONG>lm</STRONG>#0 indicates that the number of lines is not fixed, but that there is still more memory than fits on the screen. - If the terminal is one of those supported by the Unix virtual terminal + If the terminal is one of those supported by the Unix virtual terminal protocol, the terminal number can be given as <STRONG>vt</STRONG>. - Media copy strings which control an auxiliary printer connected to the - terminal can be given as <STRONG>mc0</STRONG>: print the contents of the screen, <STRONG>mc4</STRONG>: - turn off the printer, and <STRONG>mc5</STRONG>: turn on the printer. When the printer - is on, all text sent to the terminal will be sent to the printer. It - is undefined whether the text is also displayed on the terminal screen - when the printer is on. A variation <STRONG>mc5p</STRONG> takes one parameter, and - leaves the printer on for as many characters as the value of the + Media copy strings which control an auxiliary printer connected to the + terminal can be given as <STRONG>mc0</STRONG>: print the contents of the screen, <STRONG>mc4</STRONG>: + turn off the printer, and <STRONG>mc5</STRONG>: turn on the printer. When the printer + is on, all text sent to the terminal will be sent to the printer. It + is undefined whether the text is also displayed on the terminal screen + when the printer is on. A variation <STRONG>mc5p</STRONG> takes one parameter, and + leaves the printer on for as many characters as the value of the parameter, then turns the printer off. The parameter should not exceed 255. All text, including <STRONG>mc4</STRONG>, is transparently passed to the printer while an <STRONG>mc5p</STRONG> is in effect. @@ -2305,27 +2303,27 @@ normal text on top of it), <STRONG>xhp</STRONG> should be given. Teleray terminals, where tabs turn all characters moved over to blanks, - should indicate <STRONG>xt</STRONG> (destructive tabs). Note: the variable indicating - this is now "dest_tabs_magic_smso"; in older versions, it was - teleray_glitch. This glitch is also taken to mean that it is not - possible to position the cursor on top of a "magic cookie", that to - erase standout mode it is instead necessary to use delete and insert + should indicate <STRONG>xt</STRONG> (destructive tabs). Note: the variable indicating + this is now "dest_tabs_magic_smso"; in older versions, it was + teleray_glitch. This glitch is also taken to mean that it is not + possible to position the cursor on top of a "magic cookie", that to + erase standout mode it is instead necessary to use delete and insert line. The <EM>ncurses</EM> implementation ignores this glitch. - The Beehive Superbee, which is unable to correctly transmit the escape - or control/C characters, has <STRONG>xsb</STRONG>, indicating that the f1 key is used - for escape and f2 for control/C. (Only certain Superbees have this - problem, depending on the ROM.) Note that in older terminfo versions, + The Beehive Superbee, which is unable to correctly transmit the escape + or control/C characters, has <STRONG>xsb</STRONG>, indicating that the f1 key is used + for escape and f2 for control/C. (Only certain Superbees have this + problem, depending on the ROM.) Note that in older terminfo versions, this capability was called "beehive_glitch"; it is now "no_esc_ctl_c". - Other specific terminal problems may be corrected by adding more + Other specific terminal problems may be corrected by adding more capabilities of the form <STRONG>x</STRONG><EM>x</EM>. </PRE><H3><a name="h3-Pitfalls-of-Long-Entries">Pitfalls of Long Entries</a></H3><PRE> - Long terminfo entries are unlikely to be a problem; to date, no entry - has even approached terminfo's 4096-byte string-table maximum. - Unfortunately, the termcap translations are much more strictly limited + Long terminfo entries are unlikely to be a problem; to date, no entry + has even approached terminfo's 4096-byte string-table maximum. + Unfortunately, the termcap translations are much more strictly limited (to 1023 bytes), thus termcap translations of long terminfo entries can cause problems. @@ -2348,15 +2346,15 @@ Some application programs allocate more than the recommended 1K for the termcap entry; others do not. - Each termcap entry has two important sizes associated with it: before - "tc" expansion, and after "tc" expansion. "tc" is the capability that + Each termcap entry has two important sizes associated with it: before + "tc" expansion, and after "tc" expansion. "tc" is the capability that tacks on another termcap entry to the end of the current one, to add on its capabilities. If a termcap entry does not use the "tc" capability, then of course the two lengths are the same. - The "before tc expansion" length is the most important one, because it - affects more than just users of that particular terminal. This is the - length of the entry as it exists in /etc/termcap, minus the backslash- + The "before tc expansion" length is the most important one, because it + affects more than just users of that particular terminal. This is the + length of the entry as it exists in /etc/termcap, minus the backslash- newline pairs, which <STRONG>tgetent</STRONG> strips out while reading it. Some termcap libraries strip off the final newline, too (GNU termcap does not). Now suppose: @@ -2365,25 +2363,25 @@ <STRONG>o</STRONG> and the application has only allocated a 1k buffer, - <STRONG>o</STRONG> and the termcap library (like the one in BSD/OS 1.1 and GNU) reads - the whole entry into the buffer, no matter what its length, to see + <STRONG>o</STRONG> and the termcap library (like the one in BSD/OS 1.1 and GNU) reads + the whole entry into the buffer, no matter what its length, to see if it is the entry it wants, - <STRONG>o</STRONG> and <STRONG>tgetent</STRONG> is searching for a terminal type that either is the - long entry, appears in the termcap file after the long entry, or - does not appear in the file at all (so that <STRONG>tgetent</STRONG> has to search + <STRONG>o</STRONG> and <STRONG>tgetent</STRONG> is searching for a terminal type that either is the + long entry, appears in the termcap file after the long entry, or + does not appear in the file at all (so that <STRONG>tgetent</STRONG> has to search the whole termcap file). - Then <STRONG>tgetent</STRONG> will overwrite memory, perhaps its stack, and probably - core dump the program. Programs like telnet are particularly - vulnerable; modern telnets pass along values like the terminal type - automatically. The results are almost as undesirable with a termcap - library, like SunOS 4.1.3 and Ultrix 4.4, that prints warning messages - when it reads an overly long termcap entry. If a termcap library - truncates long entries, like OSF/1 3.0, it is immune to dying here but + Then <STRONG>tgetent</STRONG> will overwrite memory, perhaps its stack, and probably + core dump the program. Programs like telnet are particularly + vulnerable; modern telnets pass along values like the terminal type + automatically. The results are almost as undesirable with a termcap + library, like SunOS 4.1.3 and Ultrix 4.4, that prints warning messages + when it reads an overly long termcap entry. If a termcap library + truncates long entries, like OSF/1 3.0, it is immune to dying here but will return incorrect data for the terminal. - The "after tc expansion" length will have a similar effect to the + The "after tc expansion" length will have a similar effect to the above, but only for people who actually set <EM>TERM</EM> to that terminal type, since <STRONG>tgetent</STRONG> only does "tc" expansion once it is found the terminal type it was looking for, not while searching. @@ -2422,53 +2420,53 @@ turned off. The <EM>ncurses</EM> library handles insert-character and insert-character modes - in a slightly non-standard way to get better update efficiency. See + in a slightly non-standard way to get better update efficiency. See the <STRONG>Insert/Delete</STRONG> <STRONG>Character</STRONG> subsection above. - The parameter substitutions for <STRONG>set_clock</STRONG> and <STRONG>display_clock</STRONG> are not - documented in SVr4 or X/Open Curses. They are deduced from the + The parameter substitutions for <STRONG>set_clock</STRONG> and <STRONG>display_clock</STRONG> are not + documented in SVr4 or X/Open Curses. They are deduced from the documentation for the AT&T 505 terminal. - Be careful assigning the <STRONG>kmous</STRONG> capability. The <EM>ncurses</EM> library wants - to interpret it as <STRONG>KEY_MOUSE</STRONG>, for use by terminals and emulators like - xterm that can return mouse-tracking information in the keyboard-input + Be careful assigning the <STRONG>kmous</STRONG> capability. The <EM>ncurses</EM> library wants + to interpret it as <STRONG>KEY_MOUSE</STRONG>, for use by terminals and emulators like + xterm that can return mouse-tracking information in the keyboard-input stream. - X/Open Curses does not mention italics. Portable applications must - assume that numeric capabilities are signed 16-bit values. This - includes the <EM>no</EM><STRONG>_</STRONG><EM>color</EM><STRONG>_</STRONG><EM>video</EM> (<STRONG>ncv</STRONG>) capability. The 32768 mask value - used for italics with <STRONG>ncv</STRONG> can be confused with an absent or cancelled - <STRONG>ncv</STRONG>. If italics should work with colors, then the <STRONG>ncv</STRONG> value must be + X/Open Curses does not mention italics. Portable applications must + assume that numeric capabilities are signed 16-bit values. This + includes the <EM>no</EM><STRONG>_</STRONG><EM>color</EM><STRONG>_</STRONG><EM>video</EM> (<STRONG>ncv</STRONG>) capability. The 32768 mask value + used for italics with <STRONG>ncv</STRONG> can be confused with an absent or canceled + <STRONG>ncv</STRONG>. If italics should work with colors, then the <STRONG>ncv</STRONG> value must be specified, even if it is zero. - Different commercial ports of <EM>terminfo</EM> and <EM>curses</EM> support different - subsets of X/Open Curses and (in some cases) different extensions. - Here is a summary, accurate as of October 1995, after which the + Different commercial ports of <EM>terminfo</EM> and <EM>curses</EM> support different + subsets of X/Open Curses and (in some cases) different extensions. + Here is a summary, accurate as of October 1995, after which the commercial Unix market contracted and lost diversity. <STRONG>o</STRONG> SVr4, Solaris, and <EM>ncurses</EM> support all SVr4 capabilities. - <STRONG>o</STRONG> IRIX supports the SVr4 set and adds one undocumented extended + <STRONG>o</STRONG> IRIX supports the SVr4 set and adds one undocumented extended string capability (<STRONG>set_pglen</STRONG>). - <STRONG>o</STRONG> SVr1 and Ultrix support a restricted subset of <EM>terminfo</EM> - capabilities. The Booleans end with <STRONG>xon_xoff</STRONG>; the numerics with + <STRONG>o</STRONG> SVr1 and Ultrix support a restricted subset of <EM>terminfo</EM> + capabilities. The Booleans end with <STRONG>xon_xoff</STRONG>; the numerics with <STRONG>width_status_line</STRONG>; and the strings with <STRONG>prtr_non</STRONG>. - <STRONG>o</STRONG> HP/UX supports the SVr1 subset, plus the SVr[234] numerics - <STRONG>num_labels</STRONG>, <STRONG>label_height</STRONG>, <STRONG>label_width</STRONG>, plus function keys 11 - through 63, plus <STRONG>plab_norm</STRONG>, <STRONG>label_on</STRONG>, and <STRONG>label_off</STRONG>, plus a number + <STRONG>o</STRONG> HP/UX supports the SVr1 subset, plus the SVr[234] numerics + <STRONG>num_labels</STRONG>, <STRONG>label_height</STRONG>, <STRONG>label_width</STRONG>, plus function keys 11 + through 63, plus <STRONG>plab_norm</STRONG>, <STRONG>label_on</STRONG>, and <STRONG>label_off</STRONG>, plus a number of incompatible string table extensions. - <STRONG>o</STRONG> AIX supports the SVr1 subset, plus function keys 11 through 63, + <STRONG>o</STRONG> AIX supports the SVr1 subset, plus function keys 11 through 63, plus a number of incompatible string table extensions. <STRONG>o</STRONG> OSF/1 supports both the SVr4 set and the AIX extensions. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - Do not count on compiled (binary) <EM>terminfo</EM> entries being portable - between commercial Unix systems. At least two implementations of + Do not count on compiled (binary) <EM>terminfo</EM> entries being portable + between commercial Unix systems. At least two implementations of <EM>terminfo</EM> (those of HP-UX and AIX) diverged from those of other System V Unices after SVr1, adding extension capabilities to the string table that (in the binary format) collide with subsequent System V and X/Open @@ -2485,9 +2483,7 @@ <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG><A HREF="curs_variables.3x.html">curs_variables(3x)</A></STRONG>, <STRONG>printf(3)</STRONG>, <STRONG><A HREF="term_variables.3x.html">term_variables(3x)</A></STRONG>, <STRONG><A HREF="term.5.html">term(5)</A></STRONG>, <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> +ncurses 6.6 2025-08-16 <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -2498,7 +2494,7 @@ ncurses 6.5 2024-04-20 <STRONG><A HR <li><a href="#h3-terminfo-Entry-Syntax">terminfo Entry Syntax</a></li> <li><a href="#h3-terminfo-Capabilities-Syntax">terminfo Capabilities Syntax</a></li> <li><a href="#h3-Similar-Terminals">Similar Terminals</a></li> -<li><a href="#h3-Predefined-Capabilities">Predefined Capabilities</a></li> +<li><a href="#h3-Standard-Capabilities">Standard Capabilities</a></li> <li><a href="#h3-User-Defined-Capabilities">User-Defined Capabilities</a></li> <li><a href="#h3-A-Sample-Entry">A Sample Entry</a></li> <li><a href="#h3-Types-of-Capabilities">Types of Capabilities</a></li> diff --git a/doc/html/man/tic.1m.html b/doc/html/man/tic.1m.html index e5e6107244cf..e66e2c3b611f 100644 --- a/doc/html/man/tic.1m.html +++ b/doc/html/man/tic.1m.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: tic.1m,v 1.110 2024/04/27 17:57:06 tom Exp @ + * @Id: tic.1m,v 1.128 2025/11/12 00:49:19 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>tic 1m 2024-04-27 ncurses 6.5 User commands</TITLE> +<TITLE>tic 1m 2025-11-11 ncurses 6.6 User commands</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">tic 1m 2024-04-27 ncurses 6.5 User commands</H1> +<H1 class="no-header">tic 1m 2025-11-11 ncurses 6.6 User commands</H1> <PRE> <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG> User commands <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>tic</STRONG> - compile terminal descriptions for <EM>terminfo</EM> or <EM>termcap</EM> @@ -56,20 +54,19 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - The <STRONG>tic</STRONG> command translates a <STRONG>terminfo</STRONG> file from source format into - compiled format. The compiled format is necessary for use with the - library routines in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. + <STRONG>tic</STRONG> translates a <EM>terminfo</EM> file from source format into the compiled + format used by the <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> library. - As described in <STRONG><A HREF="term.5.html">term(5)</A></STRONG>, the database may be either a directory tree - (one file per terminal entry) or a hashed database (one record per - entry). The <STRONG>tic</STRONG> command writes only one type of entry, depending on - how it was built: + As described in <STRONG><A HREF="term.5.html">term(5)</A></STRONG>, the database may be either a directory tree + (one file per terminal entry) or a hashed database (one record per + entry). The <STRONG>tic</STRONG> command writes only one type of entry, depending on + how it was built. - <STRONG>o</STRONG> For directory trees, the top-level directory, e.g., - /usr/share/terminfo, specifies the location of the database. + <STRONG>o</STRONG> For directory trees, the top-level directory, such as + <EM>/usr/share/terminfo</EM>, specifies the location of the database. - <STRONG>o</STRONG> For hashed databases, a filename is needed. If the given file is - not found by that name, but can be found by adding the suffix + <STRONG>o</STRONG> For hashed databases, a filename is needed. If the given file is + not found by that name, but can be found by adding the suffix ".db", then that is used. The default name for the hashed database is the same as the default @@ -77,108 +74,105 @@ In either case (directory or hashed database), <STRONG>tic</STRONG> will create the container if it does not exist. For a directory, this would be the - "terminfo" leaf, versus a "terminfo.db" file. + "terminfo" leaf, versus a <EM>terminfo.db</EM> file. - The results are normally placed in the system terminfo database - <STRONG>/usr/share/terminfo</STRONG>. The compiled terminal description can be placed - in a different terminfo database. There are two ways to achieve this: + The results are normally placed in the system <EM>terminfo</EM> database + <EM>/usr/share/terminfo</EM>. The compiled terminal description can be placed + in a different <EM>terminfo</EM> database. There are two ways to achieve this: <STRONG>o</STRONG> First, you may override the system default either by using the <STRONG>-o</STRONG> - option, or by setting the variable <EM>TERMINFO</EM> in your shell + option, or by setting the variable <EM>TERMINFO</EM> in the process environment to a valid database location. <STRONG>o</STRONG> Secondly, if <STRONG>tic</STRONG> cannot write in <EM>/usr/share/terminfo</EM> or the location specified using your <EM>TERMINFO</EM> variable, it looks for the - directory <EM>$HOME/.terminfo</EM> (or hashed database <EM>$HOME/.terminfo.db)</EM>; + directory <EM>$HOME/.terminfo</EM> (or hashed database <EM>$HOME/.terminfo.db</EM>); if that location exists, the entry is placed there. - Libraries that read terminfo entries are expected to check in + Libraries that read <EM>terminfo</EM> entries are expected to check in succession - <STRONG>o</STRONG> a location specified with the <EM>TERMINFO</EM> environment variable, + <STRONG>o</STRONG> a location specified by the <EM>TERMINFO</EM> environment variable, <STRONG>o</STRONG> <EM>$HOME/.terminfo</EM>, <STRONG>o</STRONG> directories listed in the <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> environment variable, - <STRONG>o</STRONG> a compiled-in list of directories (/usr/share/terminfo), and + <STRONG>o</STRONG> a compiled-in list of directories (<EM>/usr/share/terminfo</EM>), and - <STRONG>o</STRONG> the system terminfo database (<EM>/usr/share/terminfo</EM>). + <STRONG>o</STRONG> the system <EM>terminfo</EM> database (<EM>/usr/share/terminfo</EM>). - The <EM>Fetching</EM> <EM>Compiled</EM> <EM>Descriptions</EM> section in the <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> manual - goes into further detail. + Section "Fetching Compiled Descriptions" in <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> goes into + further detail. </PRE><H3><a name="h3-Aliases">Aliases</a></H3><PRE> - This is the same program as infotocap and captoinfo; usually those are - linked to, or copied from this program: + <STRONG>tic</STRONG> is the same program as <STRONG>infotocap</STRONG> and <STRONG>captoinfo</STRONG>; usually those are + linked to, or copied from, this program. - <STRONG>o</STRONG> When invoked as infotocap, tic sets the <STRONG>-I</STRONG> option. + <STRONG>o</STRONG> When invoked as <STRONG>infotocap</STRONG>, <STRONG>tic</STRONG> sets the <STRONG>-I</STRONG> option. - <STRONG>o</STRONG> When invoked as captoinfo, tic sets the <STRONG>-C</STRONG> option. + <STRONG>o</STRONG> When invoked as <STRONG>captoinfo</STRONG>, <STRONG>tic</STRONG> sets the <STRONG>-C</STRONG> option. </PRE><H2><a name="h2-OPTIONS">OPTIONS</a></H2><PRE> - <STRONG>-0</STRONG> restricts the output to a single line + <STRONG>-0</STRONG> restricts the output to a single line. - <STRONG>-1</STRONG> restricts the output to a single column + <STRONG>-1</STRONG> restricts the output to a single column. <STRONG>-a</STRONG> tells <STRONG>tic</STRONG> to retain commented-out capabilities rather than discarding them. Capabilities are commented by prefixing them - with a period. This sets the <STRONG>-x</STRONG> option, because it treats the - commented-out entries as user-defined names. If the source is - termcap, accept the 2-character names required by version 6. + with a period. <STRONG>-a</STRONG> implies <STRONG>-x</STRONG>, because <STRONG>tic</STRONG> treats the commented- + out entries as user-defined names. If the source is in <EM>termcap</EM> + format, <STRONG>tic</STRONG> accepts the 2-character names required by version 6. Otherwise these are ignored. - <STRONG>-C</STRONG> Force source translation to termcap format. Note: this differs - from the <STRONG>-C</STRONG> option of <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG> in that it does not merely - translate capability names, but also translates terminfo strings - to termcap format. Capabilities that are not translatable are - left in the entry under their terminfo names but commented out - with two preceding dots. The actual format used incorporates - some improvements for escaped characters from terminfo format. - For a stricter BSD-compatible translation, add the <STRONG>-K</STRONG> option. - - If this is combined with <STRONG>-c</STRONG>, <STRONG>tic</STRONG> makes additional checks to - report cases where the terminfo values do not have an exact - equivalent in termcap form. For example: - - <STRONG>o</STRONG> <STRONG>sgr</STRONG> usually will not convert, because termcap lacks the - ability to work with more than two parameters, and because - termcap lacks many of the arithmetic/logical operators used - in terminfo. - - <STRONG>o</STRONG> capabilities with more than one delay or with delays before - the end of the string will not convert completely. - - <STRONG>-c</STRONG> tells <STRONG>tic</STRONG> to only check <EM>file</EM> for errors, including syntax - problems and bad use-links. If you specify <STRONG>-C</STRONG> (<STRONG>-I</STRONG>) with this - option, the code will print warnings about entries which, after - use resolution, are more than 1023 (4096) bytes long. Due to a - fixed buffer length in older termcap libraries, as well as buggy - checking for the buffer length (and a documented limit in - terminfo), these entries may cause core dumps with other + <STRONG>-C</STRONG> Force source translation to <EM>termcap</EM> format. Note: this option + differs from the <STRONG>-C</STRONG> option of <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG> in that it does not + merely translate capability names, but also translates <EM>terminfo</EM> + string capability values to <EM>termcap</EM> format. <STRONG>tic</STRONG> leaves + capabilities that are not translatable in the entry under their + <EM>terminfo</EM> names, but commented out with two preceding dots. The + actual format used incorporates some improvements for escaped + characters from <EM>terminfo</EM> format. For a stricter BSD-compatible + translation, specify <STRONG>-K</STRONG> as well. + + If <STRONG>-C</STRONG> is combined with <STRONG>-c</STRONG>, <STRONG>tic</STRONG> makes additional checks, + reporting cases where <EM>terminfo</EM> capability values do not have an + exact equivalent in <EM>termcap</EM> syntax. For example: + + <STRONG>o</STRONG> <STRONG>sgr</STRONG> usually does not convert, because <EM>termcap</EM> is unable to + work with more than two parameters, and because <EM>termcap</EM> <EM>'s</EM> + language for encoding parameterized capabilities lacks many + of <EM>terminfo</EM>'s arithmetic and logical operators. + + <STRONG>-c</STRONG> tells <STRONG>tic</STRONG> to perform only validation of <EM>file</EM> <EM>,</EM> including syntax + problems and invalid "<STRONG>use</STRONG>" references; no output is produced. + If you specify <STRONG>-C</STRONG> (<STRONG>-I</STRONG>) with this option, <STRONG>tic</STRONG> warns about entries + that, after "<STRONG>use</STRONG>" resolution, exceed 1023 (4096) bytes. Due to + a fixed buffer length in older <EM>termcap</EM> libraries, as well as + buggy checking of the buffer length (and a documented limit in + <EM>terminfo</EM>), these entries may cause core dumps with other implementations. <STRONG>tic</STRONG> checks string capabilities to ensure that those with - parameters will be valid expressions. It does this check only - for the predefined string capabilities; those which are defined - with the <STRONG>-x</STRONG> option are ignored. + parameters are valid expressions. It validates only standard + string capabilities, ignoring those defined with the <STRONG>-x</STRONG> option. <STRONG>-D</STRONG> tells <STRONG>tic</STRONG> to print the database locations that it knows about, and exit. The first location shown is the one to which it would - write compiled terminal descriptions. If <STRONG>tic</STRONG> is not able to + write compiled terminal descriptions. If <STRONG>tic</STRONG> is not able to find a writable database location according to the rules - summarized above, it will print a diagnostic and exit with an + summarized above, it will print a diagnostic and exit with an error rather than printing a list of database locations. <STRONG>-e</STRONG> <EM>list</EM> - Limit writes and translations to the comma-separated <EM>list</EM> of - terminal types. If any name or alias of a terminal matches one - of the names in the list, the entry will be written or + Limit writes and translations to the comma-separated <EM>list</EM> of + terminal types. If any name or alias of a terminal matches one + of the names in the list, the entry will be written or translated as normal. Otherwise no output will be generated for it. The option value is interpreted as a file containing the - list if it contains a '/'. (Note: depending on how tic was + list if it contains a '/'. (Note: depending on how <STRONG>tic</STRONG> was compiled, this option may require <STRONG>-I</STRONG> or <STRONG>-C</STRONG>.) <STRONG>-f</STRONG> Display complex terminfo strings which contain @@ -195,7 +189,7 @@ <STRONG>-K</STRONG> Suppress some longstanding <EM>ncurses</EM> extensions to termcap format, e.g., "\s" for space. - <STRONG>-L</STRONG> Force source translation to terminfo format using the long C + <STRONG>-L</STRONG> Force source translation to terminfo format using the long C variable names listed in <<STRONG>term.h</STRONG>> <STRONG>-N</STRONG> Disable smart defaults. Normally, when translating from termcap @@ -203,7 +197,7 @@ the defaults of string capabilities <STRONG>reset1_string</STRONG>, <STRONG>carriage_return</STRONG>, <STRONG>cursor_left</STRONG>, <STRONG>cursor_down</STRONG>, <STRONG>scroll_forward</STRONG>, <STRONG>tab</STRONG>, <STRONG>newline</STRONG>, <STRONG>key_backspace</STRONG>, <STRONG>key_left</STRONG>, and <STRONG>key_down</STRONG>, then attempts to - use obsolete termcap capabilities to deduce correct values. It + use obsolete termcap capabilities to deduce correct values. It also normally suppresses output of obsolete termcap capabilities such as <STRONG>bs</STRONG>. This option forces a more literal translation that also preserves the obsolete capabilities. @@ -228,7 +222,7 @@ Restrict output to a given subset. This option is for use with archaic versions of terminfo like those on SVr1, Ultrix, or HP- UX that do not support the full set of SVR4/XSI Curses terminfo; - and outright broken ports like AIX 3.x that have their own + and outright broken ports like AIX 3.x that have their own extensions incompatible with SVr4/XSI. Available subsets are @@ -236,40 +230,40 @@ See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for details. - <STRONG>-r</STRONG> Force entry resolution (so there are no remaining tc - capabilities) even when doing translation to termcap format. - This may be needed if you are preparing a termcap file for a - termcap library (such as GNU termcap through version 1.3 or BSD + <STRONG>-r</STRONG> Force entry resolution (so there are no remaining tc + capabilities) even when doing translation to termcap format. + This may be needed if you are preparing a termcap file for a + termcap library (such as GNU termcap through version 1.3 or BSD termcap through 4.3BSD) that does not handle multiple tc capabilities per entry. - <STRONG>-s</STRONG> Summarize the compile by showing the database location into - which entries are written, and the number of entries which are + <STRONG>-s</STRONG> Summarize the compile by showing the database location into + which entries are written, and the number of entries which are compiled. - <STRONG>-T</STRONG> eliminates size-restrictions on the generated text. This is - mainly useful for testing and analysis, since the compiled - descriptions are limited (e.g., 1023 for termcap, 4096 for + <STRONG>-T</STRONG> eliminates size-restrictions on the generated text. This is + mainly useful for testing and analysis, since the compiled + descriptions are limited (e.g., 1023 for termcap, 4096 for terminfo). - <STRONG>-t</STRONG> tells <STRONG>tic</STRONG> to discard commented-out capabilities. Normally when - translating from terminfo to termcap, untranslatable + <STRONG>-t</STRONG> tells <STRONG>tic</STRONG> to discard commented-out capabilities. Normally when + translating from terminfo to termcap, untranslatable capabilities are commented-out. - <STRONG>-U</STRONG> tells <STRONG>tic</STRONG> to not post-process the data after parsing the source - file. Normally, it infers data which is commonly missing in + <STRONG>-U</STRONG> tells <STRONG>tic</STRONG> to not post-process the data after parsing the source + file. Normally, it infers data which is commonly missing in older terminfo data, or in termcaps. - <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> which was used in this program, + <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> which was used in this program, and exits. - <STRONG>-v</STRONG><EM>n</EM> specifies that (verbose) output be written to standard error + <STRONG>-v</STRONG><EM>n</EM> specifies that (verbose) output be written to standard error trace information showing <STRONG>tic</STRONG>'s progress. - The optional parameter <EM>n</EM> is a number from 1 to 9, inclusive, + The optional parameter <EM>n</EM> is a number from 1 to 9, inclusive, indicating the desired level of detail of information. - <STRONG>o</STRONG> If <EM>ncurses</EM> is built without tracing support, the optional + <STRONG>o</STRONG> If <EM>ncurses</EM> is built without tracing support, the optional parameter is ignored. <STRONG>o</STRONG> If <EM>n</EM> is omitted, the default level is 1. @@ -316,36 +310,39 @@ </PRE><H3><a name="h3-Parameters">Parameters</a></H3><PRE> - <EM>file</EM> contains one or more <STRONG>terminfo</STRONG> terminal descriptions in source - format [see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>]. Each description in the file - describes the capabilities of a particular terminal. + <EM>file</EM> contains one or more <EM>terminfo</EM> terminal descriptions in source + format; see <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. Each description in the file describes + the capabilities of a particular terminal type. - If <EM>file</EM> is "-", then the data is read from the standard input. - The <EM>file</EM> parameter may also be the path of a character-device. + If <EM>file</EM> is "-", the data are read from the standard input + stream. The <EM>file</EM> parameter may also be the path of a character + device. </PRE><H3><a name="h3-Processing">Processing</a></H3><PRE> - All but one of the capabilities recognized by <STRONG>tic</STRONG> are documented in - <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. The exception is the <STRONG>use</STRONG> capability. - - When a <STRONG>use</STRONG>=<EM>entry</EM>-<EM>name</EM> field is discovered in a terminal entry currently - being compiled, <STRONG>tic</STRONG> reads in the binary from <STRONG>/usr/share/terminfo</STRONG> to - complete the entry. (Entries created from <EM>file</EM> will be used first. - <STRONG>tic</STRONG> duplicates the capabilities in <EM>entry</EM>-<EM>name</EM> for the current entry, - with the exception of those capabilities that explicitly are defined in - the current entry. - - When an entry, e.g., <STRONG>entry_name_1</STRONG>, contains a <STRONG>use=</STRONG><EM>entry</EM>_<EM>name</EM>_<EM>2</EM> field, - any canceled capabilities in <EM>entry</EM>_<EM>name</EM>_<EM>2</EM> must also appear in - <STRONG>entry_name_1</STRONG> before <STRONG>use=</STRONG> for these capabilities to be canceled in - <STRONG>entry_name_1</STRONG>. - - Total compiled entries cannot exceed 4096 bytes in the legacy storage - format, or 32768 using the extended number format. The name field - cannot exceed 512 bytes. Terminal names exceeding the maximum alias - length (32 characters on systems with long filenames, 14 characters - otherwise) will be truncated to the maximum alias length and a warning - message will be printed. + <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> documents all but one of the capabilities recognized by + <STRONG>tic</STRONG>. The exception is the <STRONG>use</STRONG> capability, which enables a terminal + type description to incorporate others by reference. + + <STRONG>tic</STRONG> serially reads and compiles terminal type descriptions; at any + given time, the program compiles at most one <EM>current</EM> entry. When <STRONG>tic</STRONG> + encounters a <STRONG>use=</STRONG><EM>entry-name</EM> field in the current entry, it reads the + compiled description of <EM>entry-name</EM> from <EM>/usr/share/terminfo</EM> to complete + the current entry. If <STRONG>tic</STRONG> has already compiled a description of <EM>entry-</EM> + <EM>name</EM> preceding the current entry in <EM>file</EM>, <STRONG>tic</STRONG> uses it preferentially. + <STRONG>tic</STRONG> duplicates the capabilities in <EM>entry-name</EM> for the current entry, + excepting those that the current entry explicitly defines. The + foregoing has implications for capability cancellation. When <EM>entry-1</EM> + declares "<STRONG>use=</STRONG><EM>entry-2</EM>", any canceled capabilities in <EM>entry-2</EM> must also + appear in <EM>entry-1</EM> prior to "<STRONG>use=</STRONG><EM>entry-2</EM>" for these capabilities to be + canceled in <EM>entry-1</EM>. + + Compiled entries cannot exceed 4096 bytes in the legacy storage format, + or 32768 using the extended number format. The name field cannot + exceed 512 bytes. Terminal names exceeding the maximum alias length + (32 characters on systems with long filenames, 14 characters otherwise) + will be truncated to the maximum alias length and a warning message + will be printed. </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE> @@ -362,48 +359,49 @@ </PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> - Unlike the SVr4 <STRONG>tic</STRONG> command, this implementation can actually compile - termcap sources. In fact, entries in terminfo and termcap syntax can - be mixed in a single source file. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for the list of - termcap names taken to be equivalent to terminfo names. + Unlike the SVr4 <EM>tic</EM> command, <EM>ncurses</EM> <EM>tic</EM> can compile <EM>termcap</EM> sources. + In fact, entries in <EM>terminfo</EM> and <EM>termcap</EM> syntax can be mixed in a + single source file. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> for the list of <EM>termcap</EM> capability + names <EM>ncurses</EM> <STRONG>tic</STRONG> treats as equivalent to <EM>terminfo</EM> names. - The SVr4 manual pages are not clear on the resolution rules for <STRONG>use</STRONG> - capabilities. This implementation of <STRONG>tic</STRONG> will find <STRONG>use</STRONG> targets - anywhere in the source file, or anywhere in the file tree rooted at - <EM>TERMINFO</EM> (if <EM>TERMINFO</EM> is defined), or in the user's <EM>$HOME/.terminfo</EM> - database (if it exists), or (finally) anywhere in the system's file - tree of compiled entries. + The SVr4 man pages are not clear on the resolution rules for "<STRONG>use</STRONG>" + capabilities. <EM>ncurses</EM>'s <STRONG>tic</STRONG> finds "<STRONG>use</STRONG>" targets anywhere in the source + file, or anywhere in the file tree rooted at the location in the + <EM>TERMINFO</EM> environment variable (if <EM>TERMINFO</EM> is defined), or in the + user's <EM>$HOME/.terminfo</EM> database (if it exists), or (finally) anywhere + in the system's collection of compiled entries. - The error messages from this <STRONG>tic</STRONG> have the same format as GNU C error - messages, and can be parsed by GNU Emacs's compile facility. + The error messages from <EM>ncurses</EM> <STRONG>tic</STRONG> have the same format as GNU C error + messages, and can be parsed by GNU Emacs's "compile" facility. - Aside from <STRONG>-c</STRONG> and <STRONG>-v</STRONG>, options are not portable: + Aside from <STRONG>-c</STRONG> and <STRONG>-v</STRONG>, options are not portable. - <STRONG>o</STRONG> Most of tic's options are not supported by SVr4 <STRONG>tic</STRONG>: + <STRONG>o</STRONG> Most of <EM>ncurses</EM> <STRONG>tic</STRONG>'s options are not supported by SVr4 <EM>tic</EM>. - <STRONG>-0</STRONG> <STRONG>-1</STRONG> <STRONG>-C</STRONG> <STRONG>-G</STRONG> <STRONG>-I</STRONG> <STRONG>-N</STRONG> <STRONG>-R</STRONG> <STRONG>-T</STRONG> <STRONG>-V</STRONG> <STRONG>-a</STRONG> <STRONG>-e</STRONG> <STRONG>-f</STRONG> <STRONG>-g</STRONG> <STRONG>-o</STRONG> <STRONG>-r</STRONG> <STRONG>-s</STRONG> <STRONG>-t</STRONG> <STRONG>-x</STRONG> + <STRONG>-0</STRONG> <STRONG>-1</STRONG> <STRONG>-C</STRONG> <STRONG>-G</STRONG> <STRONG>-I</STRONG> <STRONG>-N</STRONG> <STRONG>-R</STRONG> <STRONG>-T</STRONG> <STRONG>-V</STRONG> <STRONG>-a</STRONG> <STRONG>-e</STRONG> <STRONG>-f</STRONG> <STRONG>-g</STRONG> <STRONG>-o</STRONG> <STRONG>-r</STRONG> <STRONG>-s</STRONG> <STRONG>-t</STRONG> <STRONG>-x</STRONG> - <STRONG>o</STRONG> The NetBSD <STRONG>tic</STRONG> supports a few of the <EM>ncurses</EM> options + <STRONG>o</STRONG> NetBSD <EM>tic</EM> supports a few of the <EM>ncurses</EM> <STRONG>tic</STRONG> options. - <STRONG>-a</STRONG> <STRONG>-o</STRONG> <STRONG>-x</STRONG> + <STRONG>-a</STRONG> <STRONG>-o</STRONG> <STRONG>-x</STRONG> - and adds <STRONG>-S</STRONG> (a feature which does the same thing as infocmp's <STRONG>-e</STRONG> - and <STRONG>-E</STRONG> options). + <STRONG>o</STRONG> NetBSD <EM>tic</EM> also adds <STRONG>-S</STRONG>, a feature which does the same thing as + <EM>ncurses</EM> <STRONG>infocmp</STRONG>'s <STRONG>-e</STRONG> and <STRONG>-E</STRONG> options. - The SVr4 <STRONG>-c</STRONG> mode does not report bad "use=" links. + SVr4 <EM>tic</EM>'s <STRONG>-c</STRONG> mode does not report bad "<STRONG>use</STRONG>" links. - System V does not compile entries to or read entries from your - <EM>$HOME/.terminfo</EM> database unless <EM>TERMINFO</EM> is explicitly set to it. + SVr4 does not compile entries to or read entries from your + <EM>$HOME/.terminfo</EM> database unless the <EM>TERMINFO</EM> environment variable is + explicitly set to it. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - X/Open Curses, Issue 7 (2009) provides a brief description of <STRONG>tic</STRONG>. It - lists one option: <STRONG>-c</STRONG>. The omission of <STRONG>-v</STRONG> is unexpected. The change - history states that the description is derived from Tru64. According + X/Open Curses Issue 7 (2009) provides a brief description of <STRONG>tic</STRONG>. It + lists one option: <STRONG>-c</STRONG>. The omission of <STRONG>-v</STRONG> is unexpected. The change + history states that the description is derived from Tru64. According to its manual pages, that system also supported the <STRONG>-v</STRONG> option. - Shortly after Issue 7 was released, Tru64 was discontinued. As of - 2019, the surviving implementations of <STRONG>tic</STRONG> are SVr4 (AIX, HP-UX and + Shortly after Issue 7 was released, Tru64 was discontinued. As of + 2019, the surviving implementations of <STRONG>tic</STRONG> are SVr4 (AIX, HP-UX and Solaris), <EM>ncurses</EM> and NetBSD curses. The SVr4 <STRONG>tic</STRONG> programs all support the <STRONG>-v</STRONG> option. The NetBSD <STRONG>tic</STRONG> program follows X/Open's documentation, omitting the <STRONG>-v</STRONG> option. @@ -420,26 +418,26 @@ System V Release 2 provided a <STRONG>tic</STRONG> utility. It accepted a single option: <STRONG>-v</STRONG> (optionally followed by a number). According to Ross Ridge's comment in <EM>mytinfo</EM>, this version of <STRONG>tic</STRONG> was unable to represent - cancelled capabilities. - - System V Release 3 provided a different <STRONG>tic</STRONG> utility, written by Pavel - Curtis, (originally named "compile" in <EM>pcurses</EM>). This added an option - <STRONG>-c</STRONG> to check the file for errors, with the caveat that errors in "use=" - links would not be reported. System V Release 3 documented a few - warning messages which did not appear in <EM>pcurses</EM>. While the program - itself was changed little as development continued with System V - Release 4, the table of capabilities grew from 180 (<EM>pcurses</EM>) to 464 + canceled capabilities. + + System V Release 3 provided a different <STRONG>tic</STRONG> utility, written by Pavel + Curtis, (originally named "compile" in <EM>pcurses</EM>). This added an option + <STRONG>-c</STRONG> to check the file for errors, with the caveat that errors in "use=" + links would not be reported. System V Release 3 documented a few + warning messages which did not appear in <EM>pcurses</EM>. While the program + itself was changed little as development continued with System V + Release 4, the table of capabilities grew from 180 (<EM>pcurses</EM>) to 464 (Solaris). - In early development of <EM>ncurses</EM> (1993), Zeyd Ben-Halim used the table - from <EM>mytinfo</EM> to extend the <EM>pcurses</EM> table to 469 capabilities (456 - matched SVr4, 8 were only in SVr4, 13 were not in SVr4). Of those 13, - 11 were ultimately discarded (perhaps to match the draft of X/Open - Curses). The exceptions were <STRONG>memory_lock_above</STRONG> and <STRONG>memory_unlock</STRONG> (see + In early development of <EM>ncurses</EM> (1993), Zeyd Ben-Halim used the table + from <EM>mytinfo</EM> to extend the <EM>pcurses</EM> table to 469 capabilities (456 + matched SVr4, 8 were only in SVr4, 13 were not in SVr4). Of those 13, + 11 were ultimately discarded (perhaps to match the draft of X/Open + Curses). The exceptions were <STRONG>memory_lock_above</STRONG> and <STRONG>memory_unlock</STRONG> (see <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG>). - Eric Raymond incorporated parts of <EM>mytinfo</EM> into <EM>ncurses</EM> to implement - the termcap-to-terminfo source conversion, and extended that to begin + Eric Raymond incorporated parts of <EM>mytinfo</EM> into <EM>ncurses</EM> to implement + the termcap-to-terminfo source conversion, and extended that to begin development of the corresponding terminfo-to-termcap source conversion, Thomas Dickey completed that development over the course of several years. @@ -454,21 +452,21 @@ The <STRONG>-c</STRONG> option tells <STRONG>tic</STRONG> to check for problems in the terminfo source file. Continued development provides additional checks: - <STRONG>o</STRONG> <EM>pcurses</EM> had 8 warnings + <STRONG>o</STRONG> <EM>pcurses</EM> had 8 warnings. - <STRONG>o</STRONG> <EM>ncurses</EM> in 1996 had 16 warnings + <STRONG>o</STRONG> <EM>ncurses</EM> in 1996 had 16 warnings. - <STRONG>o</STRONG> Solaris (SVr4) curses has 28 warnings + <STRONG>o</STRONG> Solaris (SVr4) <EM>curses</EM> has 28 warnings. - <STRONG>o</STRONG> NetBSD tic in 2019 has 19 warnings. + <STRONG>o</STRONG> NetBSD <EM>tic</EM> in 2019 has 19 warnings. - <STRONG>o</STRONG> <EM>ncurses</EM> in 2019 has 96 warnings + <STRONG>o</STRONG> <EM>ncurses</EM> in 2019 has 96 warnings. - The checking done in <EM>ncurses</EM>' <STRONG>tic</STRONG> helps with the conversion to termcap, - as well as pointing out errors and inconsistencies. It is also used to - ensure consistency with the user-defined capabilities. There are 527 - distinct capabilities in <EM>ncurses</EM>' terminal database; 128 of those are - user-defined. + The checking done in <EM>ncurses</EM>'s <STRONG>tic</STRONG> helps with the conversion to + termcap, as well as pointing out errors and inconsistencies. It is + also used to ensure consistency with the user-defined capabilities. + There are 527 distinct capabilities in <EM>ncurses</EM>'s terminal database; 128 + of those are user-defined. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> @@ -480,9 +478,7 @@ <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG>, <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>, <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="term.5.html">term(5)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> - - -ncurses 6.5 2024-04-27 <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/toe.1m.html b/doc/html/man/toe.1m.html index c3aca2c592fd..14c82a98f274 100644 --- a/doc/html/man/toe.1m.html +++ b/doc/html/man/toe.1m.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2019-2023,2024 Thomas E. Dickey * + * Copyright 2019-2024,2025 Thomas E. Dickey * * Copyright 1998-2015,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: toe.1m,v 1.68 2024/04/20 18:59:26 tom Exp @ + * @Id: toe.1m,v 1.75 2025/11/12 01:06:36 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>toe 1m 2024-04-20 ncurses 6.5 User commands</TITLE> +<TITLE>toe 1m 2025-11-11 ncurses 6.6 User commands</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">toe 1m 2024-04-20 ncurses 6.5 User commands</H1> +<H1 class="no-header">toe 1m 2025-11-11 ncurses 6.6 User commands</H1> <PRE> <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG> User commands <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>toe</STRONG> - list table of entries of <EM>terminfo</EM> terminal types @@ -83,7 +81,7 @@ Without the <STRONG>-s</STRONG> option, <STRONG>toe</STRONG> does not attempt to merge duplicates in its report. - <STRONG>-h</STRONG> writes a heading naming each each directory as it is accessed. + <STRONG>-h</STRONG> writes a heading naming each directory as it is accessed. <STRONG>-s</STRONG> sorts the output by the entry names. @@ -91,25 +89,25 @@ source or <EM>termcap</EM> database file. The report summarizes the "<STRONG>use</STRONG>" (<EM>terminfo</EM>) and <STRONG>tc</STRONG> (<EM>termcap</EM>) relations: each line comprises the primary name of a terminal type employing <STRONG>use</STRONG>/<STRONG>tc</STRONG> - capabilities, a colon, a space- and tab-separated list of + capabilities, a colon, a space- and tab-separated list of primary names of terminal types thus named, and a newline. - <STRONG>-U</STRONG> <EM>file</EM> lists terminal type reverse dependencies in <EM>file</EM>, a <EM>terminfo</EM> - entry source or <EM>termcap</EM> database file. The report summarizes - the "<STRONG>use</STRONG>" (<EM>terminfo</EM>) and <STRONG>tc</STRONG> (<EM>termcap</EM>) reverse relations: each - line comprises the primary name of a terminal type occurring - in <STRONG>use</STRONG>/<STRONG>tc</STRONG> capabilities, a colon, a space- and tab-separated - list of primary names of terminal types naming them thus, and + <STRONG>-U</STRONG> <EM>file</EM> lists terminal type reverse dependencies in <EM>file</EM>, a <EM>terminfo</EM> + entry source or <EM>termcap</EM> database file. The report summarizes + the "<STRONG>use</STRONG>" (<EM>terminfo</EM>) and <STRONG>tc</STRONG> (<EM>termcap</EM>) reverse relations: each + line comprises the primary name of a terminal type occurring + in <STRONG>use</STRONG>/<STRONG>tc</STRONG> capabilities, a colon, a space- and tab-separated + list of primary names of terminal types naming them thus, and a newline. - <STRONG>-v</STRONG> [<EM>n</EM>] reports verbose status information to the standard error + <STRONG>-v</STRONG> [<EM>n</EM>] reports verbose status information to the standard error stream, showing <STRONG>toe</STRONG>'s progress. - The optional parameter <EM>n</EM> is an integer between 1 and 10 - inclusive, interpreted as for <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>. If <EM>ncurses</EM> is built + The optional parameter <EM>n</EM> is an integer between 1 and 10 + inclusive, interpreted as for <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>. If <EM>ncurses</EM> is built without tracing support, <EM>n</EM> is ignored. - <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> associated with this program + <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> associated with this program and exits with a successful status. @@ -119,12 +117,12 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - <STRONG>toe</STRONG> is not provided by other implementations. There is no applicable + <STRONG>toe</STRONG> is not provided by other implementations. There is no applicable X/Open or POSIX standard for it. </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - <STRONG>toe</STRONG> replaces a <STRONG>-T</STRONG> option that was briefly supported by the <EM>ncurses</EM> + <STRONG>toe</STRONG> replaces a <STRONG>-T</STRONG> option that was briefly supported by the <EM>ncurses</EM> <STRONG>infocmp</STRONG> utility in 1995. The <STRONG>-a</STRONG> and <STRONG>-s</STRONG> options were added in 2006 and 2011, respectively. @@ -139,8 +137,8 @@ </PRE><H2><a name="h2-EXAMPLES">EXAMPLES</a></H2><PRE> - When not sorting with the <STRONG>-s</STRONG> option, the <STRONG>-a</STRONG> option reports all of the - names found in all of the terminal database directories named in the + When not sorting with the <STRONG>-s</STRONG> option, the <STRONG>-a</STRONG> option reports all of the + names found in all of the terminal database directories named in the <EM>TERMINFO</EM> and <EM>TERMINFO</EM><STRONG>_</STRONG><EM>DIRS</EM> environment variables. xterm-color generic color xterm @@ -157,13 +155,12 @@ vt52 dec vt52 ... - Use the <STRONG>-a</STRONG> and <STRONG>-s</STRONG> options together to show where each terminal + Use the <STRONG>-a</STRONG> and <STRONG>-s</STRONG> options together to show where each terminal description was found. --> /etc/terminfo ----> /lib/terminfo ------> /usr/share/terminfo - --*---: vt100 dec vt100 (w/advanced video) --*---: vt102 dec vt102 --*---: vt220 dec vt220 @@ -183,9 +180,7 @@ <STRONG><A HREF="captoinfo.1m.html">captoinfo(1m)</A></STRONG>, <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="infotocap.1m.html">infotocap(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG>, <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - -ncurses 6.5 2024-04-20 <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="toe.1m.html">toe(1m)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/tput.1.html b/doc/html/man/tput.1.html index ed8fe3805afb..0371e04be063 100644 --- a/doc/html/man/tput.1.html +++ b/doc/html/man/tput.1.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,55 +28,54 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: tput.1,v 1.113 2024/04/20 19:58:50 tom Exp @ + * @Id: tput.1,v 1.149 2025/11/12 01:05:03 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>tput 1 2024-04-20 ncurses 6.5 User commands</TITLE> +<TITLE>tput 1 2025-11-11 ncurses 6.6 User commands</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">tput 1 2024-04-20 ncurses 6.5 User commands</H1> +<H1 class="no-header">tput 1 2025-11-11 ncurses 6.6 User commands</H1> <PRE> <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> User commands <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>tput</STRONG> - initialize a terminal, exercise its capabilities, or query <EM>term-</EM> <EM>info</EM> database </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> - <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] {<EM>cap-code</EM> [<EM>parameter</EM> ...]} ... + <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] {<EM>cap-code</EM> [<EM>parameter</EM> ...]} ... - <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] [<STRONG>-x</STRONG>] <STRONG>clear</STRONG> + <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] [<STRONG>-x</STRONG>] <STRONG>clear</STRONG> - <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>init</STRONG> + <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>init</STRONG> - <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>reset</STRONG> + <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>reset</STRONG> - <STRONG>tput</STRONG> [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>longname</STRONG> + <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] [<STRONG>-T</STRONG> <EM>terminal-type</EM>] <STRONG>longname</STRONG> - <STRONG>tput</STRONG> <STRONG>-S</STRONG> + <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] <STRONG>-S</STRONG> - <STRONG>tput</STRONG> <STRONG>-V</STRONG> + <STRONG>tput</STRONG> [<STRONG>-v</STRONG>] <STRONG>-V</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - <STRONG>tput</STRONG> uses the <EM>terminfo</EM> library and database to make terminal-specific - capabilities and information available to the shell, to initialize or - reset the terminal, or to report a description of the current (or - specified) terminal type. Terminal capabilities are accessed by <EM>cap-</EM> + <STRONG>tput</STRONG> uses the <EM>terminfo</EM> library and database to make terminal-specific + capabilities and information available to the shell, to initialize or + reset the terminal, or to report a description of the current (or + specified) terminal type. Terminal capabilities are accessed by <EM>cap-</EM> <EM>code</EM>. - <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> discusses terminal capabilities at length and presents a - complete list of <EM>cap-codes</EM>. + <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> discusses terminal capabilities at length and presents a + complete list of standardized <EM>cap-codes</EM>. <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> presents other + widely used but non-standard capabilities. When retrieving capability values, the result depends upon the capability's type. @@ -99,28 +98,28 @@ Generally, an operand is a <EM>cap-code</EM>, a capability code from the terminal database, or a parameter thereto. Three others are specially recognized by <STRONG>tput</STRONG>: <STRONG>init</STRONG>, <STRONG>reset</STRONG>, and <STRONG>longname</STRONG>. Although these resemble - capability codes, they in fact receive special handling; we term them + capability codes, they in fact receive special handling; we term them "pseudo-capabilities". <EM>cap-code</EM> indicates a capability from the terminal database. - If <EM>cap-code</EM> is of string type and takes parameters, <STRONG>tput</STRONG> - interprets arguments following <EM>cap-code</EM> as the parameters, + If <EM>cap-code</EM> is of string type and takes parameters, <STRONG>tput</STRONG> + interprets arguments following <EM>cap-code</EM> as the parameters, up to the (fixed) quantity the capability requires. - Most parameters are numeric. Only a few terminal + Most parameters are numeric. Only a few terminal capabilities require string parameters; <STRONG>tput</STRONG> uses a table to decide which to pass as strings. Normally <STRONG>tput</STRONG> uses <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> to perform the substitution. If no parameters are - given for the capability, <STRONG>tput</STRONG> writes the string without + given for the capability, <STRONG>tput</STRONG> writes the string without performing the substitution. - <STRONG>init</STRONG> initializes the terminal. If the terminal database is - present and an entry for the user's terminal type exists, + <STRONG>init</STRONG> initializes the terminal. If the terminal database is + present and an entry for the user's terminal type exists, the following occur. - (1) <STRONG>tput</STRONG> retrieves the terminal's mode settings. It - successively tests the file descriptors corresponding + (1) <STRONG>tput</STRONG> retrieves the terminal's mode settings. It + successively tests the file descriptors corresponding to <STRONG>o</STRONG> the standard error stream, @@ -131,73 +130,69 @@ <STRONG>o</STRONG> <EM>/dev/tty</EM> - to obtain terminal settings. Having retrieved them, - <STRONG>tput</STRONG> remembers which descriptor to use for further + to obtain terminal settings. Having retrieved them, + <STRONG>tput</STRONG> remembers which descriptor to use for further updates. - (2) If the terminal dimensions cannot be obtained from the - operating system, but the environment or terminal type - database entry describes them, <STRONG>tput</STRONG> updates the + (2) If the terminal dimensions cannot be obtained from the + operating system, but the environment or terminal type + database entry describes them, <STRONG>tput</STRONG> updates the operating system's notion of them. (3) <STRONG>tput</STRONG> updates the terminal modes. - <STRONG>o</STRONG> Any delays specified in the entry (for example, - when a newline is sent) are set in the terminal - driver. - - <STRONG>o</STRONG> Tab expansion is turned on or off per the + <STRONG>o</STRONG> Tab expansion is turned on or off per the specification in the entry, and - <STRONG>o</STRONG> if tabs are not expanded, standard tabs (every 8 + <STRONG>o</STRONG> if tabs are not expanded, standard tabs (every 8 spaces) are set. - (4) If initialization capabilities, detailed in subsection - "Tabs and Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, are present, + (4) If initialization capabilities, detailed in subsection + "Tabs and Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, are present, <STRONG>tput</STRONG> writes them to the standard output stream. (5) <STRONG>tput</STRONG> flushes the standard output stream. - If an entry lacks the information needed for an activity + If an entry lacks the information needed for an activity above, that activity is silently skipped. - <STRONG>reset</STRONG> re-initializes the terminal. A reset differs from + <STRONG>reset</STRONG> re-initializes the terminal. A reset differs from initialization in two ways. - (1) <STRONG>tput</STRONG> sets the the terminal modes to a "sane" state, + (1) <STRONG>tput</STRONG> sets the terminal modes to a "sane" state, - <STRONG>o</STRONG> enabling cooked and echo modes, + <STRONG>o</STRONG> enabling canonical ("cooked") and echo modes, <STRONG>o</STRONG> disabling cbreak and raw modes, <STRONG>o</STRONG> enabling newline translation, and - <STRONG>o</STRONG> setting any unset special characters to their + <STRONG>o</STRONG> setting any special input characters to their default values. - (2) If any reset capabilities are defined for the terminal - type, <STRONG>tput</STRONG> writes them to the output stream. - Otherwise, <STRONG>tput</STRONG> uses any defined initialization - capabilities. Reset capabilities are detailed in + (2) If any reset capabilities are defined for the terminal + type, <STRONG>tput</STRONG> writes them to the output stream. + Otherwise, <STRONG>tput</STRONG> uses any defined initialization + capabilities. Reset capabilities are detailed in subsection "Tabs and Initialization" of <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. - <STRONG>longname</STRONG> A <EM>terminfo</EM> entry begins with one or more names by which an - application can refer to the entry, before the list of - terminal capabilities. The names are separated by "|" - characters. X/Open Curses terms the last name the "long + <STRONG>longname</STRONG> A <EM>terminfo</EM> entry begins with one or more names by which an + application can refer to the entry, before the list of + terminal capabilities. The names are separated by "|" + characters. X/Open Curses terms the last name the "long name", and indicates that it may include blanks. - <STRONG>tic</STRONG> warns if the last name does not include blanks, to - accommodate old <EM>terminfo</EM> entries that treated the long name - as an optional feature. The long name is often referred to + <STRONG>tic</STRONG> warns if the last name does not include blanks, to + accommodate old <EM>terminfo</EM> entries that treated the long name + as an optional feature. The long name is often referred to as the description field. - If the terminal database is present and an entry for the + If the terminal database is present and an entry for the user's terminal type exists, <STRONG>tput</STRONG> reports its description to the standard output stream, without a trailing newline. See <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>. - <EM>Note:</EM> Redirecting the output of "<STRONG>tput</STRONG> <STRONG>init</STRONG>" or "<STRONG>tput</STRONG> <STRONG>reset</STRONG>" to a file + <EM>Note:</EM> Redirecting the output of "<STRONG>tput</STRONG> <STRONG>init</STRONG>" or "<STRONG>tput</STRONG> <STRONG>reset</STRONG>" to a file will capture only part of their actions. Changes to the terminal modes are not affected by file descriptor redirection, since the terminal modes are altered via <STRONG>ioctl(2)</STRONG>. @@ -209,20 +204,20 @@ operand. For example, executing a link named <STRONG>reset</STRONG> that points to <STRONG>tput</STRONG> has the same effect as "<STRONG>tput</STRONG> <STRONG>reset</STRONG>". - This feature was introduced by <EM>ncurses</EM> 5.2 in 2000. It is rarely used: + This feature was introduced by <EM>ncurses</EM> 5.2 in 2000. It is rarely used. <STRONG>clear</STRONG> is a separate program, which is both smaller and more frequently executed. <STRONG>init</STRONG> has the same name as another program in widespread use. - <STRONG>reset</STRONG> is provided by the <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> utility (also via a link named + <STRONG>reset</STRONG> is provided by the <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> utility (also via a link named <STRONG>reset</STRONG>). </PRE><H3><a name="h3-Terminal-Size">Terminal Size</a></H3><PRE> - Besides the pseudo-capabilities (such as <STRONG>init</STRONG>), <STRONG>tput</STRONG> treats the <STRONG>lines</STRONG> - and <STRONG>cols</STRONG> <EM>cap-codes</EM> specially: it may call <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to obtain the + Besides the pseudo-capabilities (such as <STRONG>init</STRONG>), <STRONG>tput</STRONG> treats the <STRONG>lines</STRONG> + and <STRONG>cols</STRONG> <EM>cap-codes</EM> specially: it may call <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG> to obtain the terminal size. <STRONG>o</STRONG> First, <STRONG>tput</STRONG> attempts to obtain these capabilities from the terminal @@ -259,6 +254,8 @@ environment variable. If specified, the environment variables <EM>LINES</EM> and <EM>COLUMNS</EM> are also ignored. + <STRONG>-v</STRONG> causes <STRONG>tput</STRONG> to operate verbosely, reporting warnings. + <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> associated with <STRONG>tput</STRONG>, and exits with a successful status. @@ -288,10 +285,15 @@ </PRE><H2><a name="h2-ENVIRONMENT">ENVIRONMENT</a></H2><PRE> - <STRONG>tput</STRONG> reads one environment variable. + <STRONG>tput</STRONG> reads up to three environment variables if the <STRONG>-T</STRONG> option is not + specified. + + <EM>COLUMNS</EM> specifies the width of the screen in characters. - <EM>TERM</EM> denotes the terminal type. Each terminal type is distinct, - though many are similar. The <STRONG>-T</STRONG> option overrides its value. + <EM>LINES</EM> specifies the height of the screen in characters. + + <EM>TERM</EM> denotes the terminal type. Each terminal type is distinct, + though many are similar. </PRE><H2><a name="h2-FILES">FILES</a></H2><PRE> @@ -303,56 +305,56 @@ </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - Over time <EM>ncurses</EM> <STRONG>tput</STRONG> has differed from that of System V in two + Over time <EM>ncurses</EM> <STRONG>tput</STRONG> has differed from that of System V in two important respects, one now mostly historical. - <STRONG>o</STRONG> "<STRONG>tput</STRONG> <EM>cap-code</EM>" writes to the standard output, which need not be a - terminal device. However, the operands that manipulate terminal + <STRONG>o</STRONG> "<STRONG>tput</STRONG> <EM>cap-code</EM>" writes to the standard output, which need not be a + terminal device. However, the operands that manipulate terminal modes might not use the standard output. - System V <STRONG>tput</STRONG>'s <STRONG>init</STRONG> and <STRONG>reset</STRONG> operands use logic from 4.1cBSD - <STRONG>tset</STRONG>, manipulating terminal modes. It checks the same file - descriptors (and <EM>/dev/tty</EM>) for association with a terminal device - as <EM>ncurses</EM> now does, and if none are, finally assumes a 1200 baud + System V <EM>tput</EM>'s <STRONG>init</STRONG> and <STRONG>reset</STRONG> operands use logic from 4.1cBSD + <EM>tset</EM>, manipulating terminal modes. It checks the same file + descriptors (and <EM>/dev/tty</EM>) for association with a terminal device + as <EM>ncurses</EM> now does, and if none are, finally assumes a 1200 baud terminal. When updating terminal modes, it ignores errors. - Until <EM>ncurses</EM> 6.1 (see section "HISTORY" below), <STRONG>tput</STRONG> did not + Until <EM>ncurses</EM> 6.1 (see section "HISTORY" below), <STRONG>tput</STRONG> did not modify terminal modes. It now employs a scheme similar to System V, using functions shared with <STRONG>tset</STRONG> (and ultimately based on - 4.4BSD <STRONG>tset</STRONG>). If it is not able to open a terminal (for instance, + 4.4BSD <EM>tset</EM>). If it is not able to open a terminal (for instance, when run by <STRONG>cron(1)</STRONG>), <STRONG>tput</STRONG> exits with an error status. - <STRONG>o</STRONG> System V <STRONG>tput</STRONG> assumes that the type of a <EM>cap-code</EM> operand is + <STRONG>o</STRONG> System V <EM>tput</EM> assumes that the type of a <EM>cap-code</EM> operand is numeric if all the characters of its value are decimal numbers; if they are not, it treats <EM>cap-code</EM> as a string capability. Most implementations that provide support for <EM>cap-code</EM> operands use - the <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> function to expand its parameters. That function - expects a mixture of numeric and string parameters, requiring <STRONG>tput</STRONG> + the <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> function to expand its parameters. That function + expects a mixture of numeric and string parameters, requiring <STRONG>tput</STRONG> to know which type to use. - <EM>ncurses</EM> <STRONG>tput</STRONG> uses a table to determine the parameter types for the - standard <EM>cap-code</EM> operands, and an internal function to analyze + <EM>ncurses</EM> <STRONG>tput</STRONG> uses a table to determine the parameter types for the + standard <EM>cap-code</EM> operands, and an internal function to analyze nonstandard <EM>cap-code</EM> operands. - While more reliable than System V's utility, a portability problem - is introduced by this analysis. An OpenBSD developer adapted the - internal library function from <EM>ncurses</EM> to port NetBSD's <EM>termcap</EM>- - based <STRONG>tput</STRONG> to <EM>terminfo</EM>, and modified it to interpret multiple <EM>cap-</EM> - <EM>codes</EM> (and parameters) on the command line. Portable applications - should not rely upon this feature; <EM>ncurses</EM> offers it to support + While more reliable than System V's utility, a portability problem + is introduced by this analysis. An OpenBSD developer adapted the + internal library function from <EM>ncurses</EM> to port NetBSD's <EM>termcap</EM>- + based <EM>tput</EM> to <EM>terminfo</EM>, and modified it to interpret multiple <EM>cap-</EM> + <EM>codes</EM> (and parameters) on the command line. Portable applications + should not rely upon this feature; <EM>ncurses</EM> offers it to support applications written specifically for OpenBSD. - This implementation, unlike others, accepts both <EM>termcap</EM> and <EM>terminfo</EM> - <EM>cap-codes</EM> if <EM>termcap</EM> support is compiled in. In that case, however, - the predefined <EM>termcap</EM> and <EM>terminfo</EM> codes have two ambiguities; <EM>ncurses</EM> + <EM>ncurses</EM>'s implementation of <EM>tput</EM>, unlike others, accepts both <EM>termcap</EM> + and <EM>terminfo</EM> <EM>cap-codes</EM> if <EM>termcap</EM> support is compiled in. In that + case, however, <EM>termcap</EM> and <EM>terminfo</EM> codes have two ambiguities; <EM>ncurses</EM> assumes the <EM>terminfo</EM> code. <STRONG>o</STRONG> The <EM>cap-code</EM> <STRONG>dl</STRONG> means <STRONG>delete_line</STRONG> to <EM>termcap</EM> but <STRONG>parm_delete_line</STRONG> to <EM>terminfo</EM>. <EM>termcap</EM> uses the code <STRONG>DL</STRONG> for <STRONG>parm_delete_line</STRONG>. <EM>term-</EM> <EM>info</EM> uses the code <STRONG>dl1</STRONG> for <STRONG>delete_line</STRONG>. - <STRONG>o</STRONG> The <EM>cap-code</EM> <STRONG>ed</STRONG> means <STRONG>exit_delete_mode</STRONG> to <EM>termcap</EM> but <STRONG>clr_eos</STRONG> to + <STRONG>o</STRONG> The <EM>cap-code</EM> <STRONG>ed</STRONG> means <STRONG>exit_delete_mode</STRONG> to <EM>termcap</EM> but <STRONG>clr_eos</STRONG> to <EM>terminfo</EM>. <EM>termcap</EM> uses the code <STRONG>cd</STRONG> for <STRONG>clr_eos</STRONG>. <EM>terminfo</EM> uses the code <STRONG>rmdc</STRONG> for <STRONG>exit_delete_mode</STRONG>. @@ -362,24 +364,24 @@ <STRONG>longname</STRONG>, and in 1994, NetBSD added support for the parameter- substitution features. - IEEE Std 1003.1/The Open Group Base Specifications Issue 7 - (POSIX.1-2008) documents only the <STRONG>clear</STRONG>, <STRONG>init</STRONG>, and <STRONG>reset</STRONG> operands. A + IEEE Std 1003.1/The Open Group Base Specifications Issue 7 + (POSIX.1-2008) documents only the <STRONG>clear</STRONG>, <STRONG>init</STRONG>, and <STRONG>reset</STRONG> operands. A few observations of interest arise from that selection. <STRONG>o</STRONG> <EM>ncurses</EM> supports <STRONG>clear</STRONG> as it does any other standard <EM>cap-code</EM>. The others (<STRONG>init</STRONG> and <STRONG>longname</STRONG>) do not correspond to terminal capabilities. - <STRONG>o</STRONG> The <STRONG>tput</STRONG> on SVr4-based systems such as Solaris, IRIX64, and HP-UX, + <STRONG>o</STRONG> The <EM>tput</EM> on SVr4-based systems such as Solaris, IRIX64, and HP-UX, as well as others such as AIX and Tru64, also support standard <EM>cap-</EM> <EM>code</EM> operands. <STRONG>o</STRONG> A few platforms such as FreeBSD recognize <EM>termcap</EM> codes rather than - <EM>terminfo</EM> capability codes in their respective <STRONG>tput</STRONG> commands. Since - 2010, NetBSD's <STRONG>tput</STRONG> uses <EM>terminfo</EM> codes. Before that, it (like + <EM>terminfo</EM> capability codes in their respective <EM>tput</EM> commands. Since + 2010, NetBSD's <EM>tput</EM> uses <EM>terminfo</EM> codes. Before that, it (like FreeBSD) recognized <EM>termcap</EM> codes. - Beginning in 2021, FreeBSD uses <EM>ncurses</EM> <STRONG>tput</STRONG>, configured for both + Beginning in 2021, FreeBSD uses <EM>ncurses</EM> <STRONG>tput</STRONG>, configured for both <EM>terminfo</EM> (tested first) and <EM>termcap</EM> (as a fallback). Because (apparently) all <EM>certified</EM> Unix systems support the full set of @@ -389,16 +391,16 @@ <STRONG>o</STRONG> X/Open Curses Issue 7 documents <STRONG>tput</STRONG> differently, with <EM>cap-code</EM> and the other features used in this implementation. - <STRONG>o</STRONG> That is, there are two standards for <STRONG>tput</STRONG>: POSIX (a subset) and - X/Open Curses (the full implementation). POSIX documents a subset - to avoid the complication of including X/Open Curses and the + <STRONG>o</STRONG> That is, there are two standards for <EM>tput</EM>: POSIX (a subset) and + X/Open Curses (the full implementation). POSIX documents a subset + to avoid the complication of including X/Open Curses and the terminal capability database. - <STRONG>o</STRONG> While it is certainly possible to write a <STRONG>tput</STRONG> program without - using <EM>curses</EM>, no system with a <EM>curses</EM> implementation provides a - <STRONG>tput</STRONG> utility that does not also support standard <EM>cap-codes</EM>. + <STRONG>o</STRONG> While it is certainly possible to write a <EM>tput</EM> program without + using <EM>curses</EM>, no system with a <EM>curses</EM> implementation provides a + <EM>tput</EM> utility that does not also support standard <EM>cap-codes</EM>. - X/Open Curses Issue 7 (2009) is the first version to document + X/Open Curses Issue 7 (2009) is the first version to document utilities. However that part of X/Open Curses does not follow existing practice (that is, System V <EM>curses</EM> behavior). @@ -408,78 +410,78 @@ <STRONG>o</STRONG> It assigns exit status 255 to a numeric variable that is not specified in the <EM>terminfo</EM> database. That likely is a documentation - error, mistaking the "-1" written to the standard output to - indicate an absent or cancelled numeric capability for an - (unsigned) exit status. + error, mistaking the "-1" written to the standard output to + indicate an absent or canceled numeric capability for an (unsigned) + exit status. The various System V implementations (AIX, HP-UX, Solaris) use the same exit statuses as <EM>ncurses</EM>. - NetBSD <EM>curses</EM> documents exit statuses that correspond to neither + NetBSD <EM>curses</EM> documents exit statuses that correspond to neither <EM>ncurses</EM> nor X/Open Curses. </PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> - Bill Joy wrote a <STRONG>tput</STRONG> command during development of 4BSD in October - 1980. This initial version only cleared the screen, and did not ship + Bill Joy wrote a <EM>tput</EM> command during development of 4BSD in October + 1980. This initial version only cleared the screen, and did not ship with official distributions. - System V developed a different <STRONG>tput</STRONG> command. + System V developed a different <EM>tput</EM> command. - <STRONG>o</STRONG> SVr2 (1984) provided a rudimentary <STRONG>tput</STRONG> that checked the parameter - against each predefined capability and returned the corresponding - value. This version of <STRONG>tput</STRONG> did not use <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> for - parameterized capabilities. + <STRONG>o</STRONG> SVr2 (1984) provided a rudimentary <EM>tput</EM> that checked the parameter + against each capability name and returned the corresponding value. + This version of <EM>tput</EM> did not use <STRONG><A HREF="curs_terminfo.3x.html">tparm(3x)</A></STRONG> for parameterized + capabilities. - <STRONG>o</STRONG> SVr3 (1987) replaced that with a more extensive program whose - support for <STRONG>init</STRONG> and <STRONG>reset</STRONG> operands (more than half the program) - incorporated the <STRONG>reset</STRONG> feature of BSD <STRONG>tset</STRONG> written by Eric Allman. + <STRONG>o</STRONG> SVr3 (1987) replaced that with a more extensive program whose + support for <STRONG>init</STRONG> and <STRONG>reset</STRONG> operands (more than half the program) + incorporated the <STRONG>reset</STRONG> feature of BSD <EM>tset</EM> written by Eric Allman. - <STRONG>o</STRONG> SVr4 (1989) added color initialization by using the <STRONG>orig_colors</STRONG> + <STRONG>o</STRONG> SVr4 (1989) added color initialization by using the <STRONG>orig_colors</STRONG> (<STRONG>oc</STRONG>) and <STRONG>orig_pair</STRONG> (<STRONG>op</STRONG>) capabilities in its <STRONG>init</STRONG> logic. - Keith Bostic refactored BSD <STRONG>tput</STRONG> for shipment in 4.3BSD-Tahoe (1988), - then replaced it the next year with a new implementation based on - System V <STRONG>tput</STRONG>. Bostic's version similarly accepted some parameters - named for <EM>terminfo</EM> (pseudo-)capabilities: <STRONG>clear</STRONG>, <STRONG>init</STRONG>, <STRONG>longname</STRONG>, and - <STRONG>reset</STRONG>. However, because he had only <EM>termcap</EM> available, it accepted - <EM>termcap</EM> codes for other capabilities. Also, Bostic's BSD <STRONG>tput</STRONG> did not - modify the terminal modes as the earlier BSD <STRONG>tset</STRONG> had done. - - At the same time, Bostic added a shell script named "clear" that used - <STRONG>tput</STRONG> to clear the screen. Both of these appeared in 4.4BSD, becoming - the "modern" BSD implementation of <STRONG>tput</STRONG>. + Keith Bostic refactored BSD <EM>tput</EM> for shipment in 4.3BSD-Reno (1990), + making it follow the interface of System V <EM>tput</EM> by accepting some + parameters named for <EM>terminfo</EM> (pseudo-)capabilities: <STRONG>clear</STRONG>, <STRONG>init</STRONG>, + <STRONG>longname</STRONG>, and <STRONG>reset</STRONG>. However, because he had only <EM>termcap</EM> available, + it accepted <EM>termcap</EM> codes for other capabilities. Also, Bostic's BSD + <EM>tput</EM> did not modify the terminal modes as the earlier BSD <EM>tset</EM> had + done. At the same time, Bostic added a shell script named "clear" that + used <EM>tput</EM> to clear the screen. These became the "modern" BSD + implementation of <EM>tput</EM>. The origin of <EM>ncurses</EM> <STRONG>tput</STRONG> lies outside both System V and BSD, in Ross Ridge's <EM>mytinfo</EM> package, published on <EM>comp.sources.unix</EM> in December 1992. Ridge's program made more sophisticated use of the terminal - capabilities than the BSD program. Eric Raymond used that <STRONG>tput</STRONG> program - (and other parts of <EM>mytinfo</EM>) in <EM>ncurses</EM> in June 1995. Incorporating - the portions dealing with terminal capabilities almost without change, - Raymond made improvements to the way command-line parameters were + capabilities than the BSD program. Eric Raymond used that <EM>tput</EM> program + (and other parts of <EM>mytinfo</EM>) in <EM>ncurses</EM> in June 1995. Incorporating + the portions dealing with terminal capabilities almost without change, + Raymond made improvements to the way command-line parameters were handled. Before <EM>ncurses</EM> 6.1 (2018), its <STRONG>tset</STRONG> and <STRONG>tput</STRONG> utilities differed. - <STRONG>o</STRONG> <STRONG>tset</STRONG> was more effective, resetting the terminal modes and special - characters. + <STRONG>o</STRONG> <STRONG>tset</STRONG> was more effective, resetting the terminal's modes and special + input characters. <STRONG>o</STRONG> On the other hand, <STRONG>tset</STRONG>'s repertoire of terminal capabilities for resetting the terminal was more limited; it had only equivalents of - <STRONG>reset_1string</STRONG> (<STRONG>rs1</STRONG>), <STRONG>reset_2string</STRONG> (<STRONG>rs2</STRONG>), and <STRONG>reset_file</STRONG> (<STRONG>rf</STRONG>), and + <STRONG>reset_1string</STRONG> (<STRONG>rs1</STRONG>), <STRONG>reset_2string</STRONG> (<STRONG>rs2</STRONG>), and <STRONG>reset_file</STRONG> (<STRONG>rf</STRONG>), and not the tab stop and margin update features of <STRONG>tput</STRONG>. - The <STRONG>reset</STRONG> program is traditionally an alias for <STRONG>tset</STRONG> due to its ability - to reset terminal modes and special characters. + The <EM>reset</EM> program is traditionally an alias for <STRONG>tset</STRONG> due to its ability + to reset the terminal's modes and special input characters. As of <EM>ncurses</EM> 6.1, the "reset" features of the two programs are (mostly) the same. Two minor differences remain. - <STRONG>o</STRONG> The <STRONG>tset</STRONG> program waits one second when resetting, in case the - terminal happens to be a hardware device. + <STRONG>o</STRONG> When issuing a reset, the <STRONG>tset</STRONG> program checks whether the device + appears to be a pseudoterminal (as might be used by a terminal + emulator program), and, if it does not, waits one second in case it + is communicating with a hardware terminal. - <STRONG>o</STRONG> The two programs write the terminal initialization strings to - different streams; that is, standard error for <STRONG>tset</STRONG> and standard + <STRONG>o</STRONG> The two programs write the terminal initialization strings to + different streams; that is, standard error for <STRONG>tset</STRONG> and standard output for <STRONG>tput</STRONG>. @@ -498,8 +500,8 @@ Set cursor to normal visibility. <STRONG>tput</STRONG> <STRONG>home</STRONG> - Move the cursor to row 0, column 0: the upper left corner of the - screen, usually known as the "home" cursor position. + Move the cursor to line 0, column 0: the upper left corner of + the screen, usually known as the "home" cursor position. <STRONG>tput</STRONG> <STRONG>clear</STRONG> Clear the screen: write the <STRONG>clear_screen</STRONG> capability's value to @@ -523,7 +525,7 @@ device. <STRONG>tput</STRONG> <STRONG>cup</STRONG> <STRONG>23</STRONG> <STRONG>4</STRONG> - Move the cursor to row 23, column 4. + Move the cursor to line 23, column 4. <STRONG>tput</STRONG> <STRONG>cup</STRONG> Report the value of the <STRONG>cursor_address</STRONG> (<STRONG>cup</STRONG>) capability (used @@ -551,11 +553,10 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> - <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>, <STRONG>stty(1)</STRONG>, <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>, <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>, <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG> - - + <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG>, <STRONG>stty(1)</STRONG>, <STRONG><A HREF="tabs.1.html">tabs(1)</A></STRONG>, <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG>, <STRONG><A HREF="curs_termcap.3x.html">curs_termcap(3x)</A></STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, + <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> -ncurses 6.5 2024-04-20 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="tput.1.html">tput(1)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/tset.1.html b/doc/html/man/tset.1.html index a5669568fb27..2ae0affd72d3 100644 --- a/doc/html/man/tset.1.html +++ b/doc/html/man/tset.1.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2016,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -27,25 +27,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: tset.1,v 1.85 2024/04/27 17:57:47 tom Exp @ + * @Id: tset.1,v 1.94 2025/01/19 00:51:54 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>tset 1 2024-04-27 ncurses 6.5 User commands</TITLE> +<TITLE>tset 1 2025-01-18 ncurses 6.6 User commands</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">tset 1 2024-04-27 ncurses 6.5 User commands</H1> +<H1 class="no-header">tset 1 2025-01-18 ncurses 6.6 User commands</H1> <PRE> <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> User commands <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>tset</STRONG>, <STRONG>reset</STRONG> - initialize or reset terminal state @@ -115,8 +113,10 @@ kill characters (among many other things) are set <STRONG>o</STRONG> unless the "<STRONG>-I</STRONG>" option is enabled, the terminal and tab - <EM>initialization</EM> strings are sent to the standard error output, and - <STRONG>tset</STRONG> waits one second (in case a hardware reset was issued). + <EM>initialization</EM> strings are sent to the standard error output, and, + if the terminal device does not appear to be a pseudoterminal (as + might be used by a terminal emulator program), <STRONG>tset</STRONG> waits one + second in case a hardware reset was issued. <STRONG>o</STRONG> Finally, if the erase, interrupt and line kill characters have changed, or are not set to their default values, their values are @@ -126,19 +126,19 @@ </PRE><H3><a name="h3-reset----reinitialization"><EM>reset</EM> -- reinitialization</a></H3><PRE> When invoked as <STRONG>reset</STRONG>, <STRONG>tset</STRONG> sets the terminal modes to "sane" values: - <STRONG>o</STRONG> sets cooked and echo modes, + <STRONG>o</STRONG> sets canonical ("cooked") and echo modes, <STRONG>o</STRONG> turns off cbreak and raw modes, <STRONG>o</STRONG> turns on newline translation and - <STRONG>o</STRONG> resets any unset special characters to their default values + <STRONG>o</STRONG> resets special input characters to their default values before doing the terminal initialization described above. Also, rather - than using the terminal <EM>initialization</EM> strings, it uses the terminal + than using the terminal <EM>initialization</EM> strings, it uses the terminal <EM>reset</EM> strings. - The <STRONG>reset</STRONG> command is useful after a program dies leaving a terminal in + The <STRONG>reset</STRONG> command is useful after a program dies leaving a terminal in an abnormal state: <STRONG>o</STRONG> you may have to type @@ -157,10 +157,10 @@ the terminal's capabilities into the shell's environment. This is done using the <STRONG>-s</STRONG> option. - When the <STRONG>-s</STRONG> option is specified, the commands to enter the information - into the shell's environment are written to the standard output. If - the <EM>SHELL</EM> environment variable ends in "csh", the commands are for - <STRONG>csh(1)</STRONG>, otherwise, they are for <STRONG>sh(1)</STRONG>. The <EM>csh</EM> commands set and unset + When the <STRONG>-s</STRONG> option is specified, the commands to enter the information + into the shell's environment are written to the standard output. If + the <EM>SHELL</EM> environment variable ends in "csh", the commands are for + <STRONG>csh(1)</STRONG>, otherwise, they are for <STRONG>sh(1)</STRONG>. The <EM>csh</EM> commands set and unset the shell variable <STRONG>noglob</STRONG>, leaving it unset. The following line in the <STRONG>.login</STRONG> or <STRONG>.profile</STRONG> files will initialize the environment correctly: @@ -179,31 +179,31 @@ that is, to tell <STRONG>tset</STRONG> "If I'm on this port at a particular speed, guess that I'm on that kind of terminal". - The argument to the <STRONG>-m</STRONG> option consists of an optional port type, an - optional operator, an optional baud rate specification, an optional - colon (":") character and a terminal type. The port type is a string - (delimited by either the operator or the colon character). The - operator may be any combination of ">", "<", "@", and "!"; ">" means - greater than, "<" means less than, "@" means equal to and "!" inverts - the sense of the test. The baud rate is specified as a number and is - compared with the speed of the standard error output (which should be + The argument to the <STRONG>-m</STRONG> option consists of an optional port type, an + optional operator, an optional baud rate specification, an optional + colon (":") character and a terminal type. The port type is a string + (delimited by either the operator or the colon character). The + operator may be any combination of ">", "<", "@", and "!"; ">" means + greater than, "<" means less than, "@" means equal to and "!" inverts + the sense of the test. The baud rate is specified as a number and is + compared with the speed of the standard error output (which should be the control terminal). The terminal type is a string. - If the terminal type is not specified on the command line, the <STRONG>-m</STRONG> - mappings are applied to the terminal type. If the port type and baud - rate match the mapping, the terminal type specified in the mapping - replaces the current type. If more than one mapping is specified, the + If the terminal type is not specified on the command line, the <STRONG>-m</STRONG> + mappings are applied to the terminal type. If the port type and baud + rate match the mapping, the terminal type specified in the mapping + replaces the current type. If more than one mapping is specified, the first applicable mapping is used. - For example, consider the following mapping: <STRONG>dialup>9600:vt100</STRONG>. The + For example, consider the following mapping: <STRONG>dialup>9600:vt100</STRONG>. The port type is dialup , the operator is >, the baud rate specification is 9600, and the terminal type is vt100. The result of this mapping is to - specify that if the terminal type is <STRONG>dialup</STRONG>, and the baud rate is + specify that if the terminal type is <STRONG>dialup</STRONG>, and the baud rate is greater than 9600 baud, a terminal type of <STRONG>vt100</STRONG> will be used. - If no baud rate is specified, the terminal type will match any baud - rate. If no port type is specified, the terminal type will match any - port type. For example, <STRONG>-m</STRONG> <STRONG>dialup:vt100</STRONG> <STRONG>-m</STRONG> <STRONG>:?xterm</STRONG> will cause any + If no baud rate is specified, the terminal type will match any baud + rate. If no port type is specified, the terminal type will match any + port type. For example, <STRONG>-m</STRONG> <STRONG>dialup:vt100</STRONG> <STRONG>-m</STRONG> <STRONG>:?xterm</STRONG> will cause any dialup port, regardless of baud rate, to match the terminal type vt100, and any non-dialup port type to match the terminal type ?xterm. Note, because of the leading question mark, the user will be queried on a @@ -212,7 +212,7 @@ No whitespace characters are permitted in the <STRONG>-m</STRONG> option argument. Also, to avoid problems with meta-characters, it is suggested that the entire <STRONG>-m</STRONG> option argument be placed within single quote characters, and - that <EM>csh</EM> users insert a backslash character ("\") before any + that <EM>csh</EM> users insert a backslash character ("\") before any exclamation marks ("!"). @@ -224,7 +224,7 @@ <STRONG>-e</STRONG> <EM>ch</EM> Set the erase character to <EM>ch</EM>. - <STRONG>-I</STRONG> Do not send the terminal or tab initialization strings to the + <STRONG>-I</STRONG> Do not send the terminal or tab initialization strings to the terminal. <STRONG>-i</STRONG> <EM>ch</EM> @@ -234,15 +234,15 @@ Set the line kill character to <EM>ch</EM>. <STRONG>-m</STRONG> <EM>mapping</EM> - Specify a mapping from a port type to a terminal; see subsection + Specify a mapping from a port type to a terminal; see subsection "Terminal Type Mapping". - <STRONG>-Q</STRONG> Do not display any values for the erase, interrupt and line kill - characters. Normally <STRONG>tset</STRONG> displays the values for control + <STRONG>-Q</STRONG> Do not display any values for the erase, interrupt and line kill + characters. Normally <STRONG>tset</STRONG> displays the values for control characters which differ from the system's default values. - <STRONG>-q</STRONG> The terminal type is displayed to the standard output, and the - terminal is not initialized in any way. The option "-" by itself + <STRONG>-q</STRONG> The terminal type is displayed to the standard output, and the + terminal is not initialized in any way. The option "-" by itself is equivalent but archaic. <STRONG>-r</STRONG> Print the terminal type to the standard error output. @@ -254,12 +254,12 @@ <STRONG>-V</STRONG> reports the version of <EM>ncurses</EM> which was used in this program, and exits. - <STRONG>-w</STRONG> Resize the window to match the size deduced via <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>. - Normally this has no effect, unless <STRONG>setupterm</STRONG> is not able to + <STRONG>-w</STRONG> Resize the window to match the size deduced via <STRONG><A HREF="curs_terminfo.3x.html">setupterm(3x)</A></STRONG>. + Normally this has no effect, unless <STRONG>setupterm</STRONG> is not able to detect the window size. - The arguments for the <STRONG>-e</STRONG>, <STRONG>-i</STRONG>, and <STRONG>-k</STRONG> options may either be entered as - actual characters or by using the "hat" notation, i.e., control-h may + The arguments for the <STRONG>-e</STRONG>, <STRONG>-i</STRONG>, and <STRONG>-k</STRONG> options may either be entered as + actual characters or by using the "hat" notation, i.e., control-h may be specified as "^H" or "^h". If neither <STRONG>-c</STRONG> or <STRONG>-w</STRONG> is given, both options are assumed. @@ -269,16 +269,16 @@ The <STRONG>tset</STRONG> command uses these environment variables: <EM>SHELL</EM> - tells <STRONG>tset</STRONG> whether to initialize <EM>TERM</EM> using <STRONG>sh(1)</STRONG> or <STRONG>csh(1)</STRONG> + tells <STRONG>tset</STRONG> whether to initialize <EM>TERM</EM> using <STRONG>sh(1)</STRONG> or <STRONG>csh(1)</STRONG> syntax. - <EM>TERM</EM> Denotes your terminal type. Each terminal type is distinct, + <EM>TERM</EM> Denotes your terminal type. Each terminal type is distinct, though many are similar. <EM>TERMCAP</EM> - may denote the location of a termcap database. If it is not an - absolute pathname, e.g., begins with a "/", <STRONG>tset</STRONG> removes the - variable from the environment before looking for the terminal + may denote the location of a termcap database. If it is not an + absolute pathname, e.g., begins with a "/", <STRONG>tset</STRONG> removes the + variable from the environment before looking for the terminal description. @@ -303,29 +303,29 @@ <STRONG>tset</STRONG>. The <STRONG>tset</STRONG> utility provides backward compatibility with BSD environments; - under most modern Unices, <EM>/etc/inittab</EM> and <STRONG>getty(8)</STRONG> can set <EM>TERM</EM> - appropriately for each dial-up line, obviating what was <STRONG>tset</STRONG>'s most - important use. This implementation behaves like 4.4BSD <STRONG>tset</STRONG>, with a + under most modern Unices, <EM>/etc/inittab</EM> and <STRONG>getty(8)</STRONG> can set <EM>TERM</EM> + appropriately for each dial-up line, obviating what was <STRONG>tset</STRONG>'s most + important use. This implementation behaves like 4.4BSD <STRONG>tset</STRONG>, with a few exceptions we shall consider now. - A few options are different because the <EM>TERMCAP</EM> variable is no longer + A few options are different because the <EM>TERMCAP</EM> variable is no longer supported under terminfo-based <EM>ncurses</EM>: - <STRONG>o</STRONG> The <STRONG>-S</STRONG> option of BSD <STRONG>tset</STRONG> no longer works; it prints an error + <STRONG>o</STRONG> The <STRONG>-S</STRONG> option of BSD <STRONG>tset</STRONG> no longer works; it prints an error message to the standard error and dies. <STRONG>o</STRONG> The <STRONG>-s</STRONG> option only sets <EM>TERM</EM>, not <EM>TERMCAP</EM>. - There was an undocumented 4.4BSD feature that invoking <STRONG>tset</STRONG> via a link - named "TSET" (or via any other name beginning with an upper-case + There was an undocumented 4.4BSD feature that invoking <STRONG>tset</STRONG> via a link + named "TSET" (or via any other name beginning with an upper-case letter) set the terminal to use upper-case only. This feature has been omitted. The <STRONG>-A</STRONG>, <STRONG>-E</STRONG>, <STRONG>-h</STRONG>, <STRONG>-u</STRONG> and <STRONG>-v</STRONG> options were deleted from the <STRONG>tset</STRONG> utility in - 4.4BSD. None of them were documented in 4.3BSD and all are of limited - utility at best. The <STRONG>-a</STRONG>, <STRONG>-d</STRONG>, and <STRONG>-p</STRONG> options are similarly not - documented or useful, but were retained as they appear to be in - widespread use. It is strongly recommended that any usage of these + 4.4BSD. None of them were documented in 4.3BSD and all are of limited + utility at best. The <STRONG>-a</STRONG>, <STRONG>-d</STRONG>, and <STRONG>-p</STRONG> options are similarly not + documented or useful, but were retained as they appear to be in + widespread use. It is strongly recommended that any usage of these three options be changed to use the <STRONG>-m</STRONG> option instead. The <STRONG>-a</STRONG>, <STRONG>-d</STRONG>, and <STRONG>-p</STRONG> options are therefore omitted from the usage summary above. @@ -339,7 +339,7 @@ arguments, although it is strongly recommended that such usage be fixed to explicitly specify the character. - As of 4.4BSD, executing <STRONG>tset</STRONG> as <STRONG>reset</STRONG> no longer implies the <STRONG>-Q</STRONG> option. + As of 4.4BSD, executing <STRONG>tset</STRONG> as <STRONG>reset</STRONG> no longer implies the <STRONG>-Q</STRONG> option. Also, the interaction between the - option and the <EM>terminal</EM> argument in some historic implementations of <STRONG>tset</STRONG> has been removed. @@ -391,9 +391,7 @@ <STRONG>csh(1)</STRONG>, <STRONG>sh(1)</STRONG>, <STRONG>stty(1)</STRONG>, <STRONG><A HREF="curs_terminfo.3x.html">curs_terminfo(3x)</A></STRONG>, <STRONG>tty(4)</STRONG>, <STRONG><A HREF="terminfo.5.html">terminfo(5)</A></STRONG>, <STRONG>ttys(5)</STRONG>, <STRONG>environ(7)</STRONG> - - -ncurses 6.5 2024-04-27 <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="tset.1.html">tset(1)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/user_caps.5.html b/doc/html/man/user_caps.5.html index 10b6f77649da..5b00603fda2f 100644 --- a/doc/html/man/user_caps.5.html +++ b/doc/html/man/user_caps.5.html @@ -1,7 +1,7 @@ <!-- * t **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * sale, use or other dealings in this Software without prior written * * authorization. * **************************************************************************** - * @Id: user_caps.5,v 1.49 2024/03/16 15:35:01 tom Exp @ + * @Id: user_caps.5,v 1.60 2025/11/12 01:01:01 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>user_caps 5 2024-03-16 ncurses 6.5 File formats</TITLE> +<TITLE>user_caps 5 2025-11-11 ncurses 6.6 File formats</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">user_caps 5 2024-03-16 ncurses 6.5 File formats</H1> +<H1 class="no-header">user_caps 5 2025-11-11 ncurses 6.6 File formats</H1> <PRE> <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> File formats <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> user_caps - user-defined <EM>terminfo</EM> capability format @@ -60,225 +58,231 @@ </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> </PRE><H3><a name="h3-Background">Background</a></H3><PRE> - Before <EM>ncurses</EM> 5.0, terminfo databases used a <EM>fixed</EM> <EM>repertoire</EM> of - terminal capabilities designed for the SVr2 terminal database in 1984, - and extended in stages through SVr4 (1989), and standardized in the - Single Unix Specification beginning in 1995. - - Most of the <EM>extensions</EM> in this fixed repertoire were additions to the - tables of Boolean, numeric and string capabilities. Rather than change - the meaning of an existing capability, a new name was added. The - terminfo database uses a binary format; binary compatibility was - ensured by using a header which gave the number of items in the tables - for each type of capability. The standardization was incomplete: - - <STRONG>o</STRONG> The <EM>binary</EM> <EM>format</EM> itself is not described in the X/Open Curses - documentation. Only the <EM>source</EM> <EM>format</EM> is described. - - Library developers rely upon the SVr4 documentation, and reverse- - engineering the compiled terminfo files to match the binary format. + Prior to <EM>ncurses</EM> 5.0 (1999), <EM>terminfo</EM> databases used a <EM>fixed</EM> <EM>repertoire</EM> + of terminal capabilities designed for the SVr2 terminal database in + 1984, added to in stages through SVr4 (1989), and standardized in + X/Open Curses starting in 1995. + + Most such additions to this fixed repertoire suppelmented the tables of + Boolean, numeric, and string capabilities. Rather than changing the + meaning of an existing capability, a new name was added. The <EM>terminfo</EM> + database uses a binary format; binary compatibility was ensured by + using a header that counted the number of items in the tables for each + type of capability. Because each <EM>curses</EM> vendor extended the standard + capability lists in distinct ways, a library could be programmed to + recognize only compiled <EM>terminfo</EM> entries that it was prepared to + interpret. Standardization was incomplete. + + <STRONG>o</STRONG> X/Open Curses describes only the <EM>source</EM> format, not its <EM>binary</EM> + representation on disk. + + Library developers rely upon SVr4 documentation and reverse + engineering of compiled <EM>terminfo</EM> files to match the binary format. <STRONG>o</STRONG> Lacking a standard for the binary format, most implementations copy the SVr2 binary format, which uses 16-bit signed integers, and is limited to 4096-byte entries. - The format cannot represent very large numeric capabilities, nor - can it represent large numbers of special keyboard definitions. + The SVr2 format cannot represent very large numeric capability + values, nor can it represent large numbers of key definitions, as + are required to distinguish multiple modifier keys used in + combination with a function key. <STRONG>o</STRONG> The tables of capability names differ between implementations. - Although they <EM>may</EM> provide all of the standard capability names, the - position in the tables differs because some features were added as - needed, while others were added (out of order) to comply with - X/Open Curses. + Although they <EM>may</EM> provide all of the standard capability names, + each arranges its table entries differently because some features + were added as needed, while others were added -- out of order -- + for X/Open Curses conformance. - While <EM>ncurses</EM>' repertoire of predefined capabilities is closest to - Solaris, Solaris's terminfo database has a few differences from the - list published by X/Open Curses. For example, <EM>ncurses</EM> can be - configured with tables which match the terminal databases for AIX, - HP-UX or OSF/1, rather than the default Solaris-like configuration. + While <EM>ncurses</EM>'s capability repertoire is closest to that of + Solaris, the set of capabilities supported by each vendor's <EM>term-</EM> + <EM>info</EM> database differs from the list published by X/Open Curses. + <EM>ncurses</EM> can be configured with tables that match the terminal + databases for AIX, HP-UX, or OSF/1, rather than the default + Solaris-like configuration. - <STRONG>o</STRONG> In SVr4 curses and <EM>ncurses</EM>, the terminal database is defined at - compile-time using a text file which lists the different terminal - capabilities. + <STRONG>o</STRONG> In SVr4 <EM>curses</EM> and <EM>ncurses</EM>, the terminal database is defined at + compile time by interpolating a text file that lists the different + terminal capabilities. - In principle, the text-file can be extended, but doing this - requires recompiling and reinstalling the library. The text-file - used in <EM>ncurses</EM> for terminal capabilities includes details for - various systems past the documented X/Open Curses features. For - example, <EM>ncurses</EM> supports these capabilities in each configuration: + In principle, the text file can be extended, but doing so requires + recompiling and reinstalling the library. The text file used by + <EM>ncurses</EM> for terminal capabilities includes details of extensions to + X/Open Curses made by various systems. For example, <EM>ncurses</EM> + supports the following nonstandard capabilities in each + configuration. - memory_lock - (meml) lock memory above cursor + <STRONG>memory_lock</STRONG> + (<STRONG>meml</STRONG>) lock memory above cursor - memory_unlock - (memu) unlock memory + <STRONG>memory_unlock</STRONG> + (<STRONG>memu</STRONG>) unlock memory - box_chars_1 - (box1) box characters primary set + <STRONG>box_chars_1</STRONG> + (<STRONG>box1</STRONG>) box characters primary set The memory lock/unlock capabilities were included because they were - used in the X11R6 terminal description for <STRONG>xterm(1)</STRONG>. The <EM>box1</EM> - capability is used in tic to help with terminal descriptions - written for AIX. + used in the X11R6 terminal description for <STRONG>xterm(1)</STRONG>. <STRONG>tic</STRONG> uses the + <STRONG>box1</STRONG> capability to cope with terminal descriptions written for AIX. - During the 1990s, some users were reluctant to use terminfo in spite of - its performance advantages over termcap: + During the 1990s, some application developers were reluctant to use + <EM>terminfo</EM> in spite of its performance (and other) advantages over + <EM>termcap</EM>. - <STRONG>o</STRONG> The fixed repertoire prevented users from adding features for - unanticipated terminal improvements (or required them to reuse - existing capabilities as a workaround). + <STRONG>o</STRONG> The fixed repertoire prevented users from adding support for + terminal features unanticipated by X/Open Curses (or required them + to reuse existing capabilities as a workaround). <STRONG>o</STRONG> The limitation to 16-bit signed integers was also mentioned. - Because termcap stores everything as a string, it could represent + Because <EM>termcap</EM> stores everything as a string, it could represent larger numbers. - Although termcap's extensibility was rarely used (it was never the - <EM>speaker</EM> who had actually used the feature), the criticism had a point. - <EM>ncurses</EM> 5.0 provided a way to detect nonstandard capabilities, - determine their type and optionally store and retrieve them in a way - which did not interfere with other applications. These are referred to - as <EM>user-defined</EM> <EM>capabilities</EM> because no modifications to the toolset's - predefined capability names are needed. - - The <EM>ncurses</EM> utilities <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> have a command-line option "-x" - to control whether the nonstandard capabilities are stored or - retrieved. A library function <STRONG>use_extended_names</STRONG> is provided for the + Although <EM>termcap</EM>'s extensibility was rarely used -- the claimant was + never an implementor who had actually exercised it -- the criticism had + a point. <EM>ncurses</EM> 5.0 provided a way to detect nonstandard + capabilities, to determine their type, and to optionally store and + retrieve them in a way that did not interfere with other applications. + <EM>ncurses</EM> terms these <EM>user-defined</EM> <EM>capabilities</EM> because no modifications + to the standard capability list are needed. + + The <EM>ncurses</EM> utilities <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> have a command-line option "-x" + to control whether the nonstandard capabilities are stored or + retrieved. <EM>ncurses</EM> provides <STRONG><A HREF="curs_extend.3x.html">use_extended_names(3x)</A></STRONG> to programs for the same purpose. - When compiling a terminal database, if "-x" is set, <STRONG>tic</STRONG> will store a - user-defined capability if the capability name is not one of the - predefined names. + When compiling a terminal database, if "-x" is used, <STRONG>tic</STRONG> stores a user- + defined capability if the capability name is not standard. - Because <EM>ncurses</EM> provides a termcap library interface, these user- - defined capabilities may be visible to termcap applications: + Because <EM>ncurses</EM> provides a <EM>termcap</EM> library interface, these user- + defined capabilities may be visible to <EM>termcap</EM> applications. - <STRONG>o</STRONG> The termcap interface (like all implementations of termcap) - requires that the capability names are 2-characters. + <STRONG>o</STRONG> The <EM>termcap</EM> interface (like all implementations of <EM>termcap</EM>) + restricts capability names to two characters. - When the capability is simple enough for use in a termcap - application, it is provided as a 2-character name. + When the capability is simple enough for use in a <EM>termcap</EM> + application, it is provided as a two-character name. - <STRONG>o</STRONG> There are other user-defined capabilities which refer to features - not usable in termcap, e.g., parameterized strings that use more - than two parameters or use more than the trivial expression support - provided by termcap. For these, the terminfo database should have - only capability names with 3 or more characters. + <STRONG>o</STRONG> Other user-defined capabilities employ features not usable in + <EM>termcap</EM>, such as parameterized strings that use more than two + parameters or require more powerful expressions than <EM>termcap</EM> + supports. Such capabilities should, in the <EM>terminfo</EM> database, have + names at least three characters in length. <STRONG>o</STRONG> Some terminals can send distinct strings for special keys (cursor-, keypad- or function-keys) depending on modifier keys (shift, - control, etc.). While terminfo and termcap have a set of 60 - predefined function-key names, to which a series of keys can be - assigned, that is insufficient for more than a dozen keys - multiplied by more than a couple of modifier combinations. The - <EM>ncurses</EM> database uses a convention based on <STRONG>xterm(1)</STRONG> to provide - extended special-key names. + control, etc.). While <EM>terminfo</EM> and <EM>termcap</EM> define a set of sixty + function key names, to which a series of keys can be assigned, that + is insufficient for more than a dozen keys multiplied by more than + a couple of modifier combinations. The <EM>ncurses</EM> database uses a + convention based on <STRONG>xterm(1)</STRONG> to provide extended special-key names. - Fitting that into termcap's limitation of 2-character names would - be pointless. These extended keys are available only with - terminfo. + Fitting that into <EM>termcap</EM>'s limitation of 2-character names would + be pointless. These extended keys are available only with <EM>term-</EM> + <EM>info</EM>. </PRE><H3><a name="h3-Recognized-Capabilities">Recognized Capabilities</a></H3><PRE> - The <EM>ncurses</EM> library uses the user-definable capabilities. While the - terminfo database may have other extensions, <EM>ncurses</EM> makes explicit - checks for these: + The <EM>ncurses</EM> library employs user-definable capabilities. While the + <EM>terminfo</EM> database may have other extensions, <EM>ncurses</EM> makes explicit + checks for the following. - AX <EM>Boolean</EM>, asserts that the terminal interprets SGR 39 and SGR 49 - by resetting the foreground and background color, respectively, + <STRONG>AX</STRONG> (Boolean) asserts that the terminal interprets SGR 39 and SGR 49 + by resetting the foreground and background colors, respectively, to the default. - This is a feature recognized by the <STRONG>screen</STRONG> program as well. + <STRONG>screen(1)</STRONG> recognizes this capability as well. - E3 <EM>string</EM>, tells how to clear the terminal's scrollback buffer. - When present, the <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG> program sends this before clearing the - terminal. + <STRONG>E3</STRONG> (string) tells an application how to clear the terminal's + scrollback buffer. When present, the <STRONG><A HREF="clear.1.html">clear(1)</A></STRONG> program sends this + before clearing the terminal. The command "<STRONG>tput</STRONG> <STRONG>clear</STRONG>" does the same thing. - NQ <EM>Boolean</EM>, used to suppress a consistency check in tic for the - <EM>ncurses</EM> capabilities in user6 through user9 (u6, u7, u8 and u9) - which tell how to query the terminal's cursor position and its + <STRONG>NQ</STRONG> (Boolean) suppresses a consistency check in <STRONG>tic</STRONG> for the <EM>ncurses</EM> + string capabilities <STRONG>user6</STRONG> (<STRONG>u6</STRONG>) through <STRONG>user9</STRONG> (<STRONG>u9</STRONG>), which tell an + application how to query the terminal's cursor position and its device attributes. - RGB - <EM>Boolean</EM>, <EM>number</EM> <STRONG>or</STRONG> <EM>string</EM>, used to assert that the - <STRONG>set_a_foreground</STRONG> and <STRONG>set_a_background</STRONG> capabilities correspond to - <EM>direct</EM> <EM>colors</EM>, using an RGB (red/green/blue) convention. This - capability allows the <STRONG>color_content</STRONG> function to return - appropriate values without requiring the application to - initialize colors using <STRONG>init_color</STRONG>. + <STRONG>RGB</STRONG> + (Boolean, numeric, or string) asserts that the <STRONG>set_a_foreground</STRONG> + (<STRONG>setaf</STRONG>) and <STRONG>set_a_background</STRONG> (<STRONG>setab</STRONG>) capabilities employ <EM>direct</EM> + <EM>colors</EM>, using an RGB (red/green/blue) convention. This + capability allows <STRONG><A HREF="curs_color.3x.html">color_content(3x)</A></STRONG> to return appropriate values + without requiring the application to initialize colors using + <STRONG><A HREF="curs_color.3x.html">init_color(3x)</A></STRONG>. - The capability type determines the values which <EM>ncurses</EM> sees: + The capability type determines the values <EM>ncurses</EM> sees. - <EM>Boolean</EM> - implies that the number of bits for red, green and blue are - the same. Using the maximum number of colors, <EM>ncurses</EM> adds - two, divides that sum by three, and assigns the result to red, - green and blue in that order. + Boolean + implies that the number of bits for red, green, and blue are + the same. Starting with the value of the capability + <STRONG>max_colors</STRONG> (<STRONG>colors</STRONG>; <EM>termcap:</EM> <STRONG>co</STRONG>), <EM>ncurses</EM> adds two, divides + the sum by three, and assigns the result to red, green, and + blue, in that order. If the number of bits needed for the number of colors is not a - multiple of three, the blue (and green) components lose in + multiple of three, the blue (and green) color channels lose in comparison to red. - <EM>number</EM> - tells <EM>ncurses</EM> what result to add to red, green and blue. If + numeric + tells <EM>ncurses</EM> what result to add to red, green, and blue. If <EM>ncurses</EM> runs out of bits, blue (and green) lose just as in the - <EM>Boolean</EM> case. + Boolean case. - <EM>string</EM> - explicitly list the number of bits used for red, green and - blue components as a slash-separated list of decimal integers. + string + specify the quantity of bits used for red, green, and blue + color channels as a slash-separated list of decimal integers. - Because there are several RGB encodings in use, applications - which make assumptions about the number of bits per color are - unlikely to work reliably. As a trivial case, for example, one - could define <STRONG>RGB#1</STRONG> to represent the standard eight ANSI colors, - i.e., one bit per color. + Because there are several RGB encodings in use, applications that + make assumptions about the number of bits per color channel are + unlikely to work reliably. As a trivial case, one could define + <STRONG>RGB#1</STRONG> to represent the standard eight ANSI X3.64/ECMA-48/ISO 6429 + colors using one bit per color channel. - U8 <EM>number</EM>, asserts that <EM>ncurses</EM> must use Unicode values for line- - drawing characters, and that it should ignore the alternate - character set capabilities when the locale uses UTF-8 encoding. - For more information, see the discussion of <STRONG>NCURSES_NO_UTF8_ACS</STRONG> - in <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. + <STRONG>U8</STRONG> (numeric) asserts whether <EM>ncurses</EM> must use Unicode values for + line-drawing characters, and that it should ignore the alternate + character set (ACS) capabilities when the locale uses UTF-8 + encoding. See the discussion of <STRONG>NCURSES_NO_UTF8_ACS</STRONG> in section + "ENVIRONMENT" of <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG>. Set this capability to a nonzero value to enable it. - XM <EM>string</EM>, override <EM>ncurses</EM>'s built-in string which enables/disables - <STRONG>xterm(1)</STRONG> mouse mode. + <STRONG>XM</STRONG> (string) override <EM>ncurses</EM>'s built-in string that directs <STRONG>xterm(1)</STRONG> + to enable or disable mouse mode. <EM>ncurses</EM> sends a character sequence to the terminal to initialize mouse mode, and when the user clicks the mouse buttons or (in certain modes) moves the mouse, handles the characters sent back - by the terminal to tell it what was done with the mouse. - - The mouse protocol is enabled when the <EM>mask</EM> passed in the - <STRONG>mousemask</STRONG> function is nonzero. By default, <EM>ncurses</EM> handles the - responses for the X11 xterm mouse protocol. It also knows about - the <EM>SGR</EM> <EM>1006</EM> xterm mouse protocol, but must to be told to look - for this specifically. It will not be able to guess which mode - is used, because the responses are enough alike that only - confusion would result. - - The <STRONG>XM</STRONG> capability has a single parameter. If nonzero, the mouse - protocol should be enabled. If zero, the mouse protocol should - be disabled. <EM>ncurses</EM> inspects this capability if it is present, - to see whether the 1006 protocol is used. If so, it expects the - responses to use the <EM>SGR</EM> <EM>1006</EM> xterm mouse protocol. - - The xterm mouse protocol is used by other terminal emulators. - The terminal database uses building-blocks for the various xterm - mouse protocols which can be used in customized terminal - descriptions. + by the terminal to tell the application what was done with the + mouse. + + The mouse protocol is enabled when the <EM>mask</EM> argument to the + <STRONG><A HREF="curs_mouse.3x.html">mousemask(3x)</A></STRONG> function is nonzero. By default, <EM>ncurses</EM> handles + the responses for the X11 <EM>xterm</EM> mouse protocol. It also knows + about the SGR 1006 <EM>xterm</EM> mouse protocol, but must to be told to + look for it specifically. <EM>ncurses</EM> is not be able to guess which + of the two modes is used, because the responses are enough alike + that only confusion would result. + + The <STRONG>XM</STRONG> capability has a single numeric parameter. If nonzero, + the mouse protocol should be enabled. If zero, the mouse + protocol should be disabled. <EM>ncurses</EM> inspects this capability if + it is present, to see whether the 1006 protocol is used. If so, + it expects the responses to use the SGR 1006 <EM>xterm</EM> mouse + protocol. + + The <EM>xterm</EM> mouse protocol is used by other terminal emulators. + The terminal database uses building blocks for the various <EM>xterm</EM> + mouse protocols usable in customized terminal descriptions. The terminal database building blocks for this mouse feature also - have an experimental capability <EM>xm</EM>. The "xm" capability - describes the mouse response. Currently there is no interpreter - which would use this information to make the mouse support - completely data-driven. + have an experimental capability, <STRONG>xm</STRONG>, that describes the mouse + response. No known interpreter uses this information, which + could make mouse support completely data-driven. - <EM>xm</EM> shows the format of the mouse responses. In this experimental - capability, the parameters are + <STRONG>xm</STRONG> shows the format of the mouse responses. In this experimental + capability, the parameters are as follows. <EM>p1</EM> y-ordinate @@ -296,8 +300,8 @@ <EM>p8</EM> x-ordinate ending region - Here are examples from the terminal database for the most - commonly used xterm mouse protocols: + Here are examples from the terminal database for the most + commonly used <EM>xterm</EM> mouse protocols. xterm+x11mouse|X11 xterm mouse protocol, kmous=\E[M, XM=\E[?1000%?%p1%{1}%=%th%el%;, @@ -315,20 +319,20 @@ </PRE><H3><a name="h3-Extended-Key-Definitions">Extended Key Definitions</a></H3><PRE> - Several terminals provide the ability to send distinct strings for - combinations of modified special keys. There is no standard for what + Several terminals provide the ability to send distinct strings for + combinations of modified special keys. There is no standard for what those keys can send. - Since 1999, <STRONG>xterm(1)</STRONG> has supported <EM>shift</EM>, <EM>control</EM>, <EM>alt</EM>, and <EM>meta</EM> - modifiers which produce distinct special-key strings. In a terminal - description, <EM>ncurses</EM> has no special knowledge of the modifiers used. - Applications can use the <EM>naming</EM> <EM>convention</EM> established for <STRONG>xterm</STRONG> to + Since 1999, <STRONG>xterm(1)</STRONG> has supported <EM>shift</EM>, <EM>control</EM>, <EM>alt</EM>, and <EM>meta</EM> + modifiers which produce distinct special-key strings. In a terminal + description, <EM>ncurses</EM> has no special knowledge of the modifiers used. + Applications can use the <EM>naming</EM> <EM>convention</EM> established for <EM>xterm</EM> to find these special keys in the terminal description. - Starting with the <EM>curses</EM> convention that capability codes describing - the input generated by a terminal's key caps begin with "k", and that - shifted special keys use uppercase letters in their names, <EM>ncurses</EM>'s - terminal database defines the following names and codes to which a + Starting with the <EM>curses</EM> convention that capability codes describing + the input generated by a terminal's key caps begin with "k", and that + shifted special keys use uppercase letters in their names, <EM>ncurses</EM>'s + terminal database defines the following names and codes to which a suffix is added. <STRONG>Code</STRONG> <STRONG>Description</STRONG> @@ -343,8 +347,8 @@ <STRONG>kRIT</STRONG> shifted kcuf1 (cursor forward) <STRONG>kUP</STRONG> shifted kcuu1 (cursor up) - Keycap nomenclature on the Unix systems for which <EM>curses</EM> was developed - differs from today's ubiquitous descendants of the IBM PC/AT keyboard + Keycap nomenclature on the Unix systems for which <EM>curses</EM> was developed + differs from today's ubiquitous descendants of the IBM PC/AT keyboard layout. In the foregoing, interpret "backward" as "left", "forward" as "right", "next" as "page down", and "prev(ious)" as "page up". @@ -368,20 +372,21 @@ 15 Meta + Ctrl + Alt 16 Meta + Ctrl + Alt + Shift - None of these are predefined; terminal descriptions can refer to <EM>names</EM> - which <EM>ncurses</EM> will allocate at runtime to <EM>key-codes</EM>. To use these keys - in an <EM>ncurses</EM> program, an application could do this: + <EM>ncurses</EM> defines no capabilities for modified F-keys; terminal + descriptions can refer to <EM>names</EM> that <EM>ncurses</EM> allocates at runtime to + <EM>key</EM> <EM>codes</EM>. To use these keys in an <EM>ncurses</EM> program, an application + could do this: - <STRONG>o</STRONG> using a list of extended key <EM>names</EM>, ask <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> for their + <STRONG>o</STRONG> using a list of extended key <EM>names</EM>, ask <STRONG><A HREF="curs_terminfo.3x.html">tigetstr(3x)</A></STRONG> for their values, and - <STRONG>o</STRONG> given the list of values, ask <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> for the <EM>key-code</EM> + <STRONG>o</STRONG> given the list of values, ask <STRONG><A HREF="key_defined.3x.html">key_defined(3x)</A></STRONG> for the <EM>key-code</EM> which would be returned for those keys by <STRONG><A HREF="curs_getch.3x.html">wgetch(3x)</A></STRONG>. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> - The "-x" extension feature of <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> has been adopted in - NetBSD curses. That implementation stores user-defined capabilities, + The "-x" extension feature of <STRONG>tic</STRONG> and <STRONG>infocmp</STRONG> has been adopted in + NetBSD <EM>curses</EM>. That implementation stores user-defined capabilities, but makes no use of these capabilities itself. @@ -393,17 +398,15 @@ </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="infocmp.1m.html">infocmp(1m)</A></STRONG>, <STRONG><A HREF="tic.1m.html">tic(1m)</A></STRONG> - The terminal database section <EM>NCURSES</EM> <EM>USER-DEFINABLE</EM> <EM>CAPABILITIES</EM> - summarizes commonly-used user-defined capabilities which are used in - the terminal descriptions. Some of those features are mentioned in - <STRONG>screen(1)</STRONG> or <STRONG>tmux(1)</STRONG>. + In the source form of the terminal database, <EM>terminfo.src</EM>, the section + "NCURSES USER-DEFINABLE CAPABILITIES". summarizes commonly-used user- + defined capabilities employed in the terminal descriptions. Some of + those features are mentioned in <STRONG>screen(1)</STRONG> or <STRONG>tmux(1)</STRONG>. - <EM>XTerm</EM> <EM>Control</EM> <EM>Sequences</EM> provides further information on the <STRONG>xterm(1)</STRONG> + <EM>XTerm</EM> <EM>Control</EM> <EM>Sequences</EM> provides further information on the <STRONG>xterm(1)</STRONG> features that are used in these extended capabilities. - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> +ncurses 6.6 2025-11-11 <STRONG><A HREF="user_caps.5.html">user_caps(5)</A></STRONG> </PRE> <div class="nav"> <ul> diff --git a/doc/html/man/wresize.3x.html b/doc/html/man/wresize.3x.html index b224fd393707..1f444f48f8b7 100644 --- a/doc/html/man/wresize.3x.html +++ b/doc/html/man/wresize.3x.html @@ -1,6 +1,6 @@ <!-- **************************************************************************** - * Copyright 2018-2023,2024 Thomas E. Dickey * + * Copyright 2018-2024,2025 Thomas E. Dickey * * Copyright 1998-2010,2015 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -28,25 +28,23 @@ * authorization. * **************************************************************************** * Author: Thomas E. Dickey 1996 - * @Id: wresize.3x,v 1.36 2024/03/16 15:35:01 tom Exp @ + * @Id: wresize.3x,v 1.47 2025/01/19 00:51:54 tom Exp @ --> <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"> <HTML> <HEAD> <meta http-equiv="Content-Type" content="text/html; charset=us-ascii"> <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts"> -<TITLE>wresize 3x 2024-03-16 ncurses 6.5 Library calls</TITLE> +<TITLE>wresize 3x 2025-01-18 ncurses 6.6 Library calls</TITLE> <link rel="author" href="mailto:bug-ncurses@gnu.org"> </HEAD> <BODY> -<H1 class="no-header">wresize 3x 2024-03-16 ncurses 6.5 Library calls</H1> +<H1 class="no-header">wresize 3x 2025-01-18 ncurses 6.6 Library calls</H1> <PRE> <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> Library calls <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> - - </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE> <STRONG>wresize</STRONG> - resize a <EM>curses</EM> window @@ -54,48 +52,59 @@ </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE> <STRONG>#include</STRONG> <STRONG><curses.h></STRONG> - <STRONG>int</STRONG> <STRONG>wresize(WINDOW</STRONG> <STRONG>*</STRONG><EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>lines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>columns</EM><STRONG>);</STRONG> + <STRONG>int</STRONG> <STRONG>wresize(WINDOW</STRONG> <STRONG>*</STRONG> <EM>win</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>lines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>columns</EM><STRONG>);</STRONG> </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE> - This <EM>ncurses</EM> extension to standard <EM>curses</EM> reallocates storage for a - <EM>curses</EM> window to adjust its dimensions to the specified values. If - either dimension is larger than its current value, the expanded part of - the window is filled with blanks merged with current background - rendition (as set by <STRONG><A HREF="curs_bkgd.3x.html">wbkgdset(3x)</A></STRONG>). + <STRONG>wresize</STRONG>, an <EM>ncurses</EM> extension to the <EM>curses</EM> library, reallocates + storage for <EM>win</EM>, adjusting its dimensions to <EM>lines</EM> and <EM>columns</EM>. If + either dimension is larger than its current value, <EM>ncurses</EM> fills the + expanded part of the window with the window's background character as + configured by <STRONG><A HREF="curs_bkgd.3x.html">wbkgdset(3x)</A></STRONG> (wide-character API: <STRONG><A HREF="curs_bkgrnd.3x.html">wbkgrndset(3x)</A></STRONG>). </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE> - <STRONG>wresize</STRONG> returns <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> on success. It will fail if - either of the dimensions is less than or equal to zero, or if an error - occurs while (re)allocating memory for the window. + <STRONG>wresize</STRONG> returns <STRONG>OK</STRONG> on success and <STRONG>ERR</STRONG> on failure. It fails if either + <EM>lines</EM> or <EM>columns</EM> is less than or equal to zero, or if an error occurs + while (re)allocating memory for <EM>win</EM>. </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE> - The only restriction placed on the dimensions is that they be greater - than zero. They are <EM>not</EM> compared to the <EM>curses</EM> screen dimensions; this - keeps the logic of <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> simple. The caller must ensure that - the window's dimensions fit within the actual screen dimensions. + The only restriction placed on the values of <EM>lines</EM> and <EM>columns</EM> is that + they be greater than zero. They are <EM>not</EM> compared to the dimensions of + the <EM>curses</EM> screen; this keeps the logic of <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> simple. The + caller must ensure that <EM>win</EM>'s dimensions fit within those of the + screen. + + +</PRE><H2><a name="h2-EXTENSIONS">EXTENSIONS</a></H2><PRE> + <STRONG>wresize</STRONG> is an <STRONG><A HREF="ncurses.3x.html">ncurses(3x)</A></STRONG> extension, and is not found in SVr4 <EM>curses</EM>, + 4.4BSD <EM>curses</EM>, or any other previous <EM>curses</EM> implementation. </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE> + Applications employing <EM>ncurses</EM> extensions should condition their use on + the visibility of the <STRONG>NCURSES_VERSION</STRONG> preprocessor macro. + + NetBSD <EM>curses</EM> adopted <EM>wresize</EM> in 2001 (release 1.5.3), and <EM>PDCurses</EM> in + 2004 (version 2.7). + It is not possible to resize windows with SVr4 <EM>curses</EM>. - <EM>ncurses</EM> introduced this extension in mid-1995. NetBSD <EM>curses</EM> adopted - it in 2001, and <EM>PDCurses</EM> in 2003. + +</PRE><H2><a name="h2-HISTORY">HISTORY</a></H2><PRE> + Thomas Dickey developed <EM>wresize</EM> as an extension to BSD <EM>curses</EM> in 1988, + and brought it to <EM>ncurses</EM> in mid-1995. </PRE><H2><a name="h2-AUTHORS">AUTHORS</a></H2><PRE> - Thomas Dickey (from an equivalent function written in 1988 for BSD - <EM>curses</EM>). + Thomas Dickey </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE> <STRONG><A HREF="resizeterm.3x.html">resizeterm(3x)</A></STRONG> - - -ncurses 6.5 2024-03-16 <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> +ncurses 6.6 2025-01-18 <STRONG><A HREF="wresize.3x.html">wresize(3x)</A></STRONG> </PRE> <div class="nav"> <ul> @@ -104,7 +113,9 @@ ncurses 6.5 2024-03-16 <STRONG><A HR <li><a href="#h2-DESCRIPTION">DESCRIPTION</a></li> <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li> <li><a href="#h2-NOTES">NOTES</a></li> +<li><a href="#h2-EXTENSIONS">EXTENSIONS</a></li> <li><a href="#h2-PORTABILITY">PORTABILITY</a></li> +<li><a href="#h2-HISTORY">HISTORY</a></li> <li><a href="#h2-AUTHORS">AUTHORS</a></li> <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li> </ul> diff --git a/doc/html/ncurses-intro.html b/doc/html/ncurses-intro.html index 194850246fa6..d07f6f251f55 100644 --- a/doc/html/ncurses-intro.html +++ b/doc/html/ncurses-intro.html @@ -1,7 +1,7 @@ <!-- - $Id: ncurses-intro.html,v 1.57 2022/11/26 19:33:46 tom Exp $ + $Id: ncurses-intro.html,v 1.58 2024/05/25 22:29:49 tom Exp $ **************************************************************************** - * Copyright 2019-2020,2022 Thomas E. Dickey * + * Copyright 2019-2022,2024 Thomas E. Dickey * * Copyright 2000-2013,2017 Free Software Foundation, Inc. * * * * Permission is hereby granted, free of charge, to any person obtaining a * @@ -365,9 +365,9 @@ source-code or documentation; the <code>tic</code> and <code>infocmp</code> programs are the exceptions.</p> - <p>System V Release 3 (System III UNIX) from Bell Labs featured a - rewritten and much-improved <code>curses</code> library, along - with the <code>tic</code> program (late 1986).</p> + <p>System V Release 3 from Bell Labs featured a rewritten and + much-improved <code>curses</code> library, along with the + <code>tic</code> program (late 1986).</p> <p>To recap, terminfo is based on Berkeley's termcap database, but contains a number of improvements and extensions. |