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

   1 '\" te
   2 .\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1996, 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 INNSTR 3XCURSES "Jun 5, 2002"
   7 .SH NAME
   8 innstr, instr, mvinnstr, mvinstr, mvwinnstr, mvwinstr, winnstr, winstr \-
   9 retrieve a multibyte character string (without rendition)
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
  14 \fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]
  15
  16 \fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]
  17
  18 :#include <curses.h>
  19
  20 \fBint\fR \fBinnstr\fR(\fBchar *\fR\fIstr\fR, \fBint\fR \fIn\fR);
  21 .fi
  22
  23 .LP
  24 .nf
  25 \fBint\fR \fBinstr\fR(\fBchar *\fR\fIstr\fR);
  26 .fi
  27
  28 .LP
  29 .nf
  30 \fBint\fR \fBmvinnstr\fR(\fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBchar *\fR\fIstr\fR, \fBint\fR \fIn\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBint\fR \fBmvinstr\fR(\fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBchar *\fR\fIstr\fR);
  36 .fi
  37
  38 .LP
  39 .nf
  40 \fBint\fR \fBmvwinnstr\fR(\fBWINDOW *\fR\fIwin\fR, \fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBchar *\fR\fIstr\fR, \fBint\fR \fIn\fR);
  41 .fi
  42
  43 .LP
  44 .nf
  45 \fBint\fR \fBmvwinstr\fR(\fBWINDOW *\fR\fIwin\fR, \fBint\fR \fIy\fR, \fBint\fR \fIx\fR, \fBchar *\fR\fIstr\fR);
  46 .fi
  47
  48 .LP
  49 .nf
  50 \fBint\fR \fBwinstr\fR(\fBWINDOW *\fR\fIwin\fR, \fBchar *\fR\fIstr\fR);
  51 .fi
  52
  53 .LP
  54 .nf
  55 \fBint\fR \fBwinnstr\fR(\fBWINDOW *\fR\fIwin\fR, \fBchar *\fR\fIstr\fR, \fBint\fR \fIn\fR);
  56 .fi
  57
  58 .SH PARAMETERS
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fIstr\fR\fR
  63 .ad
  64 .RS 7n
  65 Is a pointer to an object that can hold the retrieved multibyte character
  66 string.
  67 .RE
  68
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fIn\fR\fR
  73 .ad
  74 .RS 7n
  75 Is the number of characters not to exceed when retrieving \fIstr\fR.
  76 .RE
  77
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fIy\fR\fR
  82 .ad
  83 .RS 7n
  84 Is the y (row) coordinate of the starting position of the string to be
  85 retrieved.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fIx\fR\fR
  92 .ad
  93 .RS 7n
  94 Is the x (column) coordinate of the starting position of the string to  be
  95 retrieved.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fIwin\fR\fR
 102 .ad
 103 .RS 7n
 104 Is a pointer to the window in which the string is to be retrieved.
 105 .RE
 106
 107 .SH DESCRIPTION
 108 .sp
 109 .LP
 110 The \fBinstr()\fR and \fBwinstr()\fR functions retrieve a multibyte character
 111 string (without attributes) starting at the current cursor position  of the
 112 \fBstdscr\fR window and window \fIwin\fR, respectively, and ending at the right
 113 margin. The \fBmvinstr()\fR and \fBmvwinstr()\fR functions retrieve a multibyte
 114 character string located at the position indicated by the \fIx\fR (column) and
 115 \fIy\fR (row) parameters (the former in the \fBstdscr\fR window; the latter  in
 116 window \fIwin\fR).
 117 .sp
 118 .LP
 119 The \fBinnstr()\fR, \fBwinnstr()\fR, \fBmvinnstr()\fR, and  \fBmvwinnstr()\fR
 120 functions retrieve at most \fIn\fR characters from the  window \fBstdscr\fR and
 121 \fIwin\fR, respectively.  The former two functions retrieve the string starting
 122 at the current cursor position; the latter two commands return the string,
 123 starting at the position  specified by the \fIx\fR and \fIy\fR parameters.
 124 .sp
 125 .LP
 126 All these functions store the retrieved string in the object pointed to by
 127 \fIstr\fR. They only store complete multibyte characters.   If the area pointed
 128 to by \fIstr\fR is not large enough to hold at least one  character, these
 129 functions fail.
 130 .sp
 131 .LP
 132 Only the character portion of the character/rendition pair is returned.  To
 133 return the complete character/rendition pair, use \fBwinchstr()\fR.
 134 .SH ERRORS
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBOK\fR\fR
 139 .ad
 140 .RS 7n
 141 Successful completion.
 142 .RE
 143
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBERR\fR\fR
 148 .ad
 149 .RS 7n
 150 An error occurred.
 151 .RE
 152
 153 .SH USAGE
 154 .sp
 155 .LP
 156 All functions except \fBwinnstr()\fR may be macros.
 157 .SH ATTRIBUTES
 158 .sp
 159 .LP
 160 See \fBattributes\fR(5) for descriptions of the following attributes:
 161 .sp
 162
 163 .sp
 164 .TS
 165 box;
 166 c | c
 167 l | l .
 168 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 169 _
 170 Interface Stability     Standard
 171 _
 172 MT-Level        Unsafe
 173 .TE
 174
 175 .SH SEE ALSO
 176 .sp
 177 .LP
 178 \fBinch\fR(3XCURSES), \fBinchstr\fR(3XCURSES), \fBlibcurses\fR(3XCURSES),
 179 \fBattributes\fR(5), \fBstandards\fR(5)