1m_transform_layout(3LAYOLUaTy)out Service Library Functimo_ntsransform_layout(3LAYOUT)
2
3
4

NAME

6       m_transform_layout - layout transformation
7

SYNOPSIS

9       cc [ flag... ] file... -llayout [ library... ]
10       #include <sys/layout.h>
11
12
13
14       int m_transform_layout(LayoutObject layout_object,
15            const char *InpBuf, const size_t ImpSize, const void *OutBuf,
16            size_t *Outsize, size_t *InpToOut, size_t *OutToInp,
17            unsigned char *Property, size_t *InpBufIndex);
18
19

DESCRIPTION

21       The   m_transform_layout()  function  performs  layout  transformations
22       (reordering, shaping, cell determination) or provides additional infor‐
23       mation  needed  for layout transformation (such as the expected size of
24       the transformed layout, the nesting level of different segments in  the
25       text  and  cross-references  between the locations of the corresponding
26       elements before and after the layout transformation).  Both  the  input
27       text and output text are character strings.
28
29
30       The  m_transform_layout()  function transforms the input text in InpBuf
31       according to the current layout values  in  layout_object.  Any  layout
32       value whose value type is LayoutTextDescriptor describes the attributes
33       of the InpBuf and OutBuf arguments. If the attributes are the same  for
34       both InpBuf and OutBuf, a null transformation is performed with respect
35       to that specific layout value.
36
37
38       The InpBuf argument specifies the source  text  to  be  processed.  The
39       InpBuf  may  not  be NULL, unless there is a need to reset the internal
40       state.
41
42
43       The InpSize argument is the number of bytes within InpBuf  to  be  pro‐
44       cessed  by  the  transformation. Its value will not change after return
45       from the transformation. InpSize set to −1 indicates that the  text  in
46       InpBuf  is  delimited  by a null code element. If InpSize is not set to
47       −1, it is possible to have some null elements in the input buffer. This
48       might  be used, for example, for a "one shot" transformation of several
49       strings, separated by nulls.
50
51
52       Output of this function may be one or more of the  following  depending
53       on the setting of the arguments:
54
55       OutBuf      Any  transformed  data  is  stored  in OutBuf, converted to
56                   ShapeCharset.
57
58
59       Outsize     The number of bytes in OutBuf.
60
61
62       InpToOut    A cross-reference from each  InpBuf  code  element  to  the
63                   transformed  data.  The cross-reference relates to the data
64                   in InpBuf starting with the first element that  InpBufIndex
65                   points  to (and not necessarily starting from the beginning
66                   of the InpBuf).
67
68
69       OutToInp    A cross-reference to each  InpBuf  code  element  from  the
70                   transformed  data.  The cross-reference relates to the data
71                   in InpBuf starting with the first element that  InpBufIndex
72                   points  to (and not necessarily starting from the beginning
73                   of the InpBuf).
74
75
76       Property    A weighted value  that  represents  peculiar  input  string
77                   transformation  properties  with  different connotations as
78                   explained below.  If this argument is not a  null  pointer,
79                   it  represents  an  array of values with the same number of
80                   elements as the source substring text before the  transfor‐
81                   mation. Each byte will contain relevant "property" informa‐
82                   tion of the corresponding element in InpBuf  starting  from
83                   the element pointed by InpBufIndex. The four rightmost bits
84                   of each "property" byte will contain information for  bidi‐
85                   rectional environments (when ActiveDirectional is True) and
86                   they will mean "NestingLevels." The possible value  from  0
87                   to  15  represents  the  nesting level of the corresponding
88                   element in the InpBuf starting from the element pointed  by
89                   InpBufIndex.  If  ActiveDirectional is false the content of
90                   NestingLevel bits will be ignored. The leftmost bit of each
91                   "property"  byte  will  contain  a "new cell indicator" for
92                   composed character environments, and will have a  value  of
93                   either  1  (for an element in InpBuf that is transformed to
94                   the beginning of a new cell) or 0  (for  the  "zero-length"
95                   composing  character  elements, when these are grouped into
96                   the same presentation cell with a non-composing character).
97                   Here again, each element of "property" pertains to the ele‐
98                   ments in the InpBuf starting from the  element  pointed  by
99                   InpBufIndex.  (Remember  that  this  is not necessarily the
100                   beginning of InpBuf). If none of the transformation proper‐
101                   ties  is  required, the argument Property can be NULL.  The
102                   use of "property" can be enhanced in the future to  pertain
103                   to other possible usage in other environments.
104
105
106
107       The  InpBufIndex  argument  is  an  offset value to the location of the
108       transformed text. When m_transform_layout() is called, InpBufIndex con‐
109       tains  the  offset  to  the  element in InpBuf that will be transformed
110       first. (Note that this is not necessarily the first element in InpBuf).
111       At  the return from the transformation, InpBufIndex contains the offset
112       to the first element in the InpBuf that has not  been  transformed.  If
113       the  entire  substring  has  been transformed successfully, InpBufIndex
114       will be incremented by the amount defined by InpSize.
115
116
117       Each of these output arguments may be NULL to specify that no output is
118       desired  for  the specific argument, but at least one of them should be
119       set to a non-null value to perform any significant work.
120
121
122       The layout object maintains a directional state  that  keeps  track  of
123       directional  changes, based on the last segment transformed. The direc‐
124       tional state is maintained across calls to  the  layout  transformation
125       functions  and allows stream data to be processed with the layout func‐
126       tions. The directional state is reset to its initial state whenever any
127       of  the  layout values TypeOfText, Orientation, or ImplicitAlg is modi‐
128       fied by means of a call to m_setvalues_layout().
129
130
131       The layout_object argument specifies a  LayoutObject  returned  by  the
132       m_create_layout() function.
133
134
135       The  OutBufargument contains the transformed data. This argument can be
136       specified as a null pointer to indicate that  no  transformed  data  is
137       required.
138
139
140       The  encoding of the OutBuf argument depends on the ShapeCharset layout
141       value defined in layout_object. If the ActiveShapeEditing layout  value
142       is not set (False), the encoding of OutBuf is guaranteed to be the same
143       as the codeset of the locale associated with the  LayoutObject  defined
144       by layout_object.
145
146
147       On  input, the OutSize argument specifies the size of the output buffer
148       in number of bytes. The output buffer should be large enough to contain
149       the  transformed  result;  otherwise,  only a partial transformation is
150       performed. If the ActiveShapeEditing layout value  is  set  (True)  the
151       OutBuf  should  be allocated to contain at least the InpSize multiplied
152       by ShapeCharsetSize.
153
154
155       On return, the OutSize argument is modified to  the  actual  number  of
156       bytes placed in OutBuf.
157
158
159       When the OutSize argument is specified as zero, the function calculates
160       the size of an output buffer large enough to  contain  the  transformed
161       text, and the result is returned in this field. The content of the buf‐
162       fers specified by InpBuf and OutBuf,  and  the  value  of  InpBufIndex,
163       remain  unchanged. If OutSize = NULL, the EINVAL error condition should
164       be returned.
165
166
167       If the InpToOut argument is not a null pointer, it points to  an  array
168       of values with the same number of bytes in InpBuf starting with the one
169       pointed by InpBufIndex and up to the end of the substring in  the  buf‐
170       fer.  On  output, the nth value in InpToOut corresponds to the nth byte
171       in InpBuf. This value is the index (in units of  bytes)  in  OutBufthat
172       identifies  the  transformed  ShapeCharset  element  of the nth byte in
173       InpBuf. In the case of multibyte encoding, the index points  (for  each
174       of  the bytes of a code element in the InpBuf) to the first byte of the
175       transformed code element in the OutBuf.
176
177
178       InpToOut may be specified as NULL if no index array from InpBuf to Out‐
179       Buf is desired.
180
181
182       If  the  OutToInp argument is not a null pointer, it points to an array
183       of values with the same number of bytes as contained in OutBuf. On out‐
184       put,  the  nth  value in OutToInp corresponds to the nth byte in OutBuf
185       This value is the index in InpBuf, starting with the byte pointed to by
186       InpBufIndex,  that  identifies the logical code element of the nth byte
187       in OutBuf. In the case of multibyte encoding, the index will point  for
188       each  of  the  bytes of a transformed code element in the OutBuf to the
189       first byte of the code element in the InpBuf.
190
191
192       OutToInp may be specified as NULL if no  index  array  from  OutBuf  to
193       InpBuf is desired.
194
195
196       To  perform  shaping  of  a text string without reordering of code ele‐
197       ments, the layout_object should be set with  input  and  output  layout
198       value  TypeOfText set to TEXT_VISUAL and both in and out of Orientation
199       set to the same value.
200

RETURN VALUES

202       If successful, the m_transform_layout() function returns 0.  If  unsuc‐
203       cessful,  the returned value is −1 and the errno is set to indicate the
204       source of error. When the size of OutBuf is not large enough to contain
205       the  entire  transformed  text,  the input text state at the end of the
206       uncompleted transformation is saved internally and the error  condition
207       E2BIG is returned in errno.
208

ERRORS

210       The m_transform_layout() function may fail if:
211
212       E2BIG     The output buffer is full and the source text is not entirely
213                 processed.
214
215
216       EBADF     The layout values are set to a meaningless combination or the
217                 layout object is not valid.
218
219
220       EILSEQ    Transformation stopped due to an input code element that can‐
221                 not be shaped or is invalid. The InpBufIndex argument is  set
222                 to  indicate  the code element causing the error. The suspect
223                 code element is either a valid code  element  but  cannot  be
224                 shaped  into  the ShapeCharset layout value, or is an invalid
225                 code element not defined by the codeset of the locale of lay‐
226                 out_object. The mbtowc() and wctomb() functions, when used in
227                 the same locale as the LayoutObject, can be used to determine
228                 if the code element is valid.
229
230
231       EINVAL    Transformation   stopped   due  to  an  incomplete  composite
232                 sequence at the end of the input buffer, or OutSize  contains
233                 NULL.
234
235
236       ERANGE    More  than  15  embedding levels are in source text or InpBuf
237                 contain unbalanced directional layout information  (push/pop)
238                 or  an incomplete composite sequence has been detected in the
239                 input buffer at the beginning of the  string  pointed  to  by
240                 InpBufIndex.
241
242                 An incomplete composite sequence at the end of the input buf‐
243                 fer is not always detectable. Sometimes, the  fact  that  the
244                 sequence  is incomplete will only be detected when additional
245                 character elements belonging to the  composite  sequence  are
246                 found at the beginning of the next input buffer.
247
248

USAGE

250       A  LayoutObject  will  have  a meaningful combination of default layout
251       values. Whoever chooses to change the default layout values is  respon‐
252       sible for making sure that the combination of layout values is meaning‐
253       ful. Otherwise, the result  of  m_transform_layout()  might  be  unpre‐
254       dictable or implementation-specific with errno set to EBADF.
255

ATTRIBUTES

257       See attributes(5) for descriptions of the following attributes:
258
259
260
261
262       ┌─────────────────────────────┬─────────────────────────────┐
263       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
264       ├─────────────────────────────┼─────────────────────────────┤
265       │Interface Stability          │Standard                     │
266       ├─────────────────────────────┼─────────────────────────────┤
267       │MT-Level                     │MT-Safe                      │
268       └─────────────────────────────┴─────────────────────────────┘
269

SEE ALSO

271       attributes(5), standards(5)
272
273
274
275SunOS 5.11                        7 Aug 2006       m_transform_layout(3LAYOUT)
Impressum