GSSTRING(3) Library Routines GSSTRING(3)
NAME
GIinit, GIchange, GIfree, GOinit, GOchange, GOfree, __C2GS, __C2GSMAL
LOC, __GS2C, __GS2CMALLOC - GSString and ResultBuf handling routines
SYNOPSIS
#include <types.h>
#include <gno/gno.h>
GSStringPtr GIinit (word len, const char *str);
GSStringPtr GIchange (GSStringPtr org, word len, const char *str);
void GIfree (GSStringPtr str);
ResultBufPtr GOinit (word len, const char *str);
ResultBufPtr GOchange (ResultBufPtr org, word len, const char *str);
void GOfree (ResultBufPtr str);
GSStringPtr __C2GS (char *str, GSStringPtr gp);
GSStringPtr __C2GSMALLOC (const char *str);
char * __GS2C (char *str, GSStringPtr gp);
char * __GS2CMALLOC (GSStringPtr gp);
DESCRIPTION
There are some occasionally undesired restrictions in the way GS/OS in‐
put and output strings are handled by the Orca/C headers. Fixed length
strings have one advantage (they are slightly easier to handle than dy‐
namic ones), and several disadvantages:
If they're too small, they're too small. If you think that no‐
body will construct a pathname more than 255 characters long, I
heartily recommend Can't Happen or /* NOTREACHED */ or Real Pro
grams Dump Core, by Ian Darwin and Geoff Collyer, USENIX Associ‐
ation Winter Conference, Dallas 1985 Proceedings.
They take up memory regardless of whether or not it's used.
They're a hassle when you want to write reentrant code. With
stack space at a premium on the IIgs, an automatic GSString255
or ResultBuf255 is out of the question. A static or global one
might get you into sync problems.
These routines solve the above problems in a simple way. There are now
six new struct pointers declared, GSStringPtr, GSStringHndl, GSStringH
ndlPtr, ResultBufPtr, ResultBufHndl, and ResultBufHndlPtr. These are
dynamic counterparts to the GSString255Ptr and similar pointers defined
by default in the Orca/C <types.h> header, and may be used in place of
those default Orca/C pointers in the various tool box calls (although a
cast may be required to quiesce the compiler). The key difference is
that the application programmer is able to specify the size of the
strings, rather than going with the default 32 or 255 bytes.
Note that there is no GSString or ResultBuf typedef, as the structures
to which these pointers refer should not be used directly; unless prop‐
erly allocated, they have a text space of only one byte.
GIinit
GSStrings must be allocated and initialized using the GIinit (or
GIchange) routines. On success, the length field of the struc‐
ture pointed to by GIinit will be set to len, and the text field
will be len+1 bytes long. The extra (last) byte in this field
is provided so that it can be used for a NULL terminating byte.
If str is non-NULL, it's contents (which is assumed to be a
NULL-terminated C string) will be copied into the text field, up
to a maximum of len bytes, and will be NULL terminated. If str
is NULL, a NULL-terminating byte will be placed in both the
first and final byte positions in the text field. On failure,
GIinit will return the NULL pointer.
GIchange
The GIchange routine is used to change the size of a GSString.
It is similar to GIinit (GIinit is implemented in terms of
GIchange), except that it takes an additional parameter, org,
which is a GSStringPtr holding the result of a previous call to
either GIinit or GIchange.
If org is NULL, GIchange behaves exactly like GIinit. If org is
non-NULL, then the GSString pointed to by org will be copied
into the returned result, and the memory pointed to by org will
no longer be usable. Note that if len is greater than the pre‐
vious length of org and str is NULL, the latter part of the text
field will be uninitialized, except that there will be a termi‐
nating NULL byte at the end of the text field (as well as the
original NULL-terminating byte at the end of the old text
field).
On success, GIchange returns the new GSString. On failure it
returns NULL and sets errno.
Note that if this call succeeds, the region pointed to by org
subsequently may not be legally referenced. If the call fails,
org is unchanged.
GIfree
GIfree is used to deallocate memory allocated with either GIinit
or GIchange. It is currently implemented as a macro.
GOinit
GOchange
The behavior of GOinit and GOchange are similar to the routines
GIinit and GIchange, respectively, except that if str is NULL,
the bufString->length and bufString->text fields of the result
will be unmodified, unless:
org is also NULL, in which case these fields are set to
be the empty string; or
len is less than the length of the GSString org, in which
case the bufString->length is set to len.
A terminating NULL byte will always be placed in the last char‐
acter of bufString->text.
GOfree
GOfree is used to deallocate memory allocated with either GOinit
or GOchange. It is currently implemented as a macro.
__C2GSMALLOC
__C2GSMALLOC takes a C-style string str and returns a GSString‐
Ptr pointing to a Class 1 GS/OS string containing a copy of str.
The returned GS/OS string will have an NULL-terminating extra
byte in the text field. Space allocated by this routine should
be released with GIfree when it is no longer required. On fail‐
ure the NULL pointer is returned.
__C2GS
__C2GS converts a C string to a Class 1 GS/OS string, where gp
points to space for the result which is already allocated. The
required space for this routine is:
sizeof(word) + strlen(str) + 1
Failure to provide sufficient space may result in memory corrup‐
tion; this routine should be used with caution. If the C string
is too long to fit in a GS/OS string, __C2GS returns NULL and
sets errno.
__GS2CMALLOC
__GS2CMALLOC is similar to __C2GSMALLOC, but the direction of
conversion is reversed. The result of __GS2CMALLOC will be a
pointer to memory allocated by malloc(3) and should be released
with free(3) when it is no longer required.
__GS2C
__GS2C is similar to __C2GS, but the direction of conversion is
reversed. __GS2C expects the memory region pointed to by str to
be sufficiently large to hold the result (this should be at
least gp->length + 1); if this is not so, then memory corruption
may occur. __GS2C always returns str.
CAVEATS
Although these routines operate in similar ways, it is an error to mix
these routines. For example, the bufString field of a ResultBuf cannot
be resized using GIchange; instead GOchange must be used.
AUTHOR
The GI and GO routines are based on code by Soenke Behrens
<s_behrens@emulex.com>.
The remaining routines were reimplemented from spec by Devin Reade
<gdr@gno.org>.
HISTORY
The GI and GO routines first appeared in the GSString Library under
slightly different names.
__C2GSMALLOC, __GS2CMALLOC, and __GS2C first appeared in GNO v1.0.
SEE ALSO
GS/OS Reference Manual
GNO 15 December 1996 GSSTRING(3)
Man(1) output converted with
man2html