usr/src/man/man3xcurses/tgetent.3xcurses

   1 '\" te
   2 .\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH TGETENT 3XCURSES "Jun 5, 2002"
   7 .SH NAME
   8 tgetent, tgetflag, tgetnum, tgetstr, tgoto \- emulate the termcap database
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
  13 \fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]
  14
  15 \fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]
  16
  17 #include <term.h>
  18
  19 \fBint\fR \fBtgetent\fR(\fBchar *\fR\fIbp\fR, \fBconst char *\fR\fIname\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBtgetflag\fR(\fBchar\fR \fIid\fR[2]);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBint\fR \fBtgetnum\fR(\fBchar\fR \fIid\fR[2]);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBchar *\fR\fBtgetstr\fR(\fBchar\fR \fIid\fR[2], \fBchar **\fR\fIarea\fR);
  35 .fi
  36
  37 .LP
  38 .nf
  39 \fBchar *\fR\fBtgoto\fR(\fBchar *\fR\fIcap\fR, \fBint\fR \fIcol\fR, \fBint\fR \fIrow\fR);
  40 .fi
  41
  42 .SH PARAMETERS
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIbp\fR\fR
  47 .ad
  48 .RS 8n
  49 Is a pointer to a buffer. This parameter is ignored.
  50 .RE
  51
  52 .sp
  53 .ne 2
  54 .na
  55 \fB\fIname\fR\fR
  56 .ad
  57 .RS 8n
  58 Is the \fBtermcap\fR entry to look up.
  59 .RE
  60
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fIcap\fR\fR
  65 .ad
  66 .RS 8n
  67 Is the pointer to a \fBtermcap\fR capability.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fIarea\fR\fR
  74 .ad
  75 .RS 8n
  76 Is a pointer to the area where \fBtgetstr()\fR stores the decoded string.
  77 .RE
  78
  79 .sp
  80 .ne 2
  81 .na
  82 \fB\fIcol\fR\fR
  83 .ad
  84 .RS 8n
  85 Is the column placement of the new cursor.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fIrow\fR\fR
  92 .ad
  93 .RS 8n
  94 Is the row placement of the new cursor.
  95 .RE
  96
  97 .SH DESCRIPTION
  98 .sp
  99 .LP
 100 The \fBtgetent()\fR function looks up the \fBtermcap\fR entry for \fIname\fR.
 101 The emulation ignores the buffer pointer \fIbp\fR.
 102 .sp
 103 .LP
 104 The \fBtgetflag()\fR function gets the Boolean entry for \fIid\fR.
 105 .sp
 106 .LP
 107 The \fBtgetnum()\fR function gets the numeric entry for \fIid\fR.
 108 .sp
 109 .LP
 110 The \fBtgetstr()\fR function gets the string entry for \fIid\fR. If \fIarea\fR
 111 is not a null pointer and does not point to a null pointer, \fBtgetstr()\fR
 112 copies the string entry into the buffer pointed to by *\fIarea\fR and advances
 113 the variable pointed to by \fIarea\fR to the first byte after the copy of the
 114 string entry.
 115 .sp
 116 .LP
 117 The \fBtgoto()\fR function instantiates the parameters \fIcol\fR and \fIrow\fR
 118 into the capability \fIcap\fR and returns a pointer to the resulting string.
 119 .sp
 120 .LP
 121 All of the information available in the \fBterminfo\fR database need not be
 122 available through these functions.
 123 .SH RETURN VALUES
 124 .sp
 125 .LP
 126 Upon successful completion, those functions that return integers return
 127 \fBOK\fR. Otherwise, they return \fBERR\fR.
 128 .sp
 129 .LP
 130 Those functions that return pointers return a null pointer when an error
 131 occurs.
 132 .SH ERRORS
 133 .sp
 134 .LP
 135 No errors are defined.
 136 .SH USAGE
 137 .sp
 138 .LP
 139 These functions are included as a conversion aid for programs that use the
 140 \fBtermcap\fR library. Their arguments are the same and the functions are
 141 emulated using the \fBterminfo\fR database.
 142 .sp
 143 .LP
 144 These functions are only guaranteed to operate reliably on character sets in
 145 which each character fits into a single byte, whose attributes can be expressed
 146 using only constants with the \fBA_\fR prefix.
 147 .sp
 148 .LP
 149 Any terminal capabilities from the \fBterminfo\fR database that cannot be
 150 retrieved using these functions can be retrieved using the functions described
 151 on the \fBtigetflag\fR(3XCURSES) manual page.
 152 .sp
 153 .LP
 154 Portable applications must use \fBtputs\fR(3XCURSES) to output the strings
 155 returned by \fBtgetstr()\fR and \fBtgoto()\fR.
 156 .SH ATTRIBUTES
 157 .sp
 158 .LP
 159 See \fBattributes\fR(5) for descriptions of the following attributes:
 160 .sp
 161
 162 .sp
 163 .TS
 164 box;
 165 c | c
 166 l | l .
 167 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 168 _
 169 Interface Stability     Standard
 170 _
 171 MT-Level        Unsafe
 172 .TE
 173
 174 .SH SEE ALSO
 175 .sp
 176 .LP
 177 \fBlibcurses\fR(3XCURSES), \fBputp\fR(3XCURSES), \fBsetupterm\fR(3XCURSES),
 178 \fBtigetflag\fR(3XCURSES), \fBattributes\fR(5), \fBstandards\fR(5)