GSSTRING(3)

NAME
GIinit, GIchange, GIfree, GOinit, GOchange, GOfree, __C2GS, __C2GSMALLOC, __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 input and output strings are handled by the Orca/C headers. Fixed length strings have one advantage (they are slightly easier to handle than dynamic ones), and several disadvantages:

    If they're too small, they're too small. If you think that nobody will construct a pathname more than 255 characters long, I heartily recommend Can't Happen or /* NOTREACHED */ or Real Programs Dump Core, by Ian Darwin and Geoff Collyer, USENIX Association 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, GSStringHndlPtr, 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 properly 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 structure 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 previous length of org and str is NULL, the latter part of the text field will be uninitialized, except that there will be a terminating 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 character 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 GSStringPtr 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 failure 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 corruption; 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@myrias.com>.

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