ncurses 6.5 - patch 20240518

[ncurses.git] / man / curs_beep.3x

diff --git a/man/curs_beep.3x b/man/curs_beep.3x
index 579931ccc47f64a5c9c41ec368034b38559b6c49..6a01deca2e8a6ac854b02855c7cc2d26491323c4 100644 (file)
--- a/man/curs_beep.3x
+++ b/man/curs_beep.3x
@@ -1,5 +1,6 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998,2003 Free Software Foundation, Inc.                   *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
+.\" Copyright 1998-2005,2010 Free Software Foundation, Inc.                  *
 .\"                                                                          *
 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
 .\" copy of this software and associated documentation files (the            *
@@ -26,38 +27,84 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_beep.3x,v 1.9 2003/12/27 18:44:30 tom Exp $
-.TH curs_beep 3X ""
+.\" $Id: curs_beep.3x,v 1.31 2024/05/18 20:06:33 tom Exp $
+.TH curs_beep 3X 2024-05-18 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
 .SH NAME
-\fBbeep\fR, \fBflash\fR - \fBcurses\fR bell and screen flash routines
+\fB\%beep\fP,
+\fB\%flash\fP \-
+ring the (visual) bell of the terminal with \fIcurses\fR
 .SH SYNOPSIS
-\fB#include <curses.h>\fR
+.nf
+\fB#include <curses.h>
 .PP
-\fBint beep(void);\fR
-.br
-\fBint flash(void);\fR
-.br
+\fBint beep(void);
+\fBint flash(void);
+.fi
 .SH DESCRIPTION
-The \fBbeep\fR and \fBflash\fR routines are used to alert the terminal user.
-The routine \fBbeep\fR sounds an audible alarm on the terminal, if possible;
-otherwise it flashes the screen (visible bell).  The routine \fBflash\fR
-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.
+.B beep
+and
+.B flash
+alert the terminal user:
+the former by sounding the terminal's audible alarm,
+and the latter by visibly attracting user 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,
+.I curses
+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.
 .SH RETURN VALUE
-These routines return \fBOK\fR if they succeed in beeping or flashing,
-\fBERR\fR otherwise.
+These functions return
+.B OK
+on success and
+.B ERR
+on failure.
+.PP
+In
+.IR \%ncurses ","
+.B beep
+and
+.B flash
+return
+.B OK
+if the terminal type supports the corresponding capability:
+.B bell
+.RB ( bel )
+for
+.B beep
+and
+.B \%flash_screen
+.RB ( flash )
+for
+.BR flash "."
+Otherwise they return
+.BR ERR "."
 .SH EXTENSIONS
-SVr4's beep and flash routines always returned \fBOK\fR, so it was not
-possible to tell when the beep or flash failed.
+In
+.IR \%ncurses ","
+these functions can return
+.BR ERR "."
 .SH PORTABILITY
-These functions are defined in the XSI Curses standard, Issue 4.  Like SVr4, it
-specifies that they always return \fBOK\fR.
+X/Open Curses,
+Issue 4 describes these functions.
+It specifies no error conditions for them.
+.PP
+On SVr4
+.IR curses ","
+they always return
+.BR OK ","
+and X/Open Curses specifies them as doing so.
+.SH HISTORY
+.B beep
+and
+.B flash
+appeared in SVr2 (1984).
 .SH SEE ALSO
-\fBcurses\fR(3X)
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fB\%curses\fP(3X),
+\fB\%terminfo\fP(5)