gno/usr.man/man3/GSString.3

.\" Man page by Devin Reade
.\"
.\" $Id: GSString.3,v 1.2 1999/07/03 14:44:55 gdr-ftp Exp $
.\"
.TH GSSTRING 3 "15 December 1996" GNO "Library Routines"
.SH NAME
.BR GIinit ,
.BR GIchange ,
.BR GIfree ,
.BR GOinit ,
.BR GOchange ,
.BR GOfree ,
.BR __C2GS ,
.BR __C2GSMALLOC ,
.BR __GS2C ,
.BR __GS2CMALLOC 
\- GSString and ResultBuf handling routines
.SH SYNOPSIS
#include <types.h>
.br
#include <gno/gno.h>
.sp 1
GSStringPtr GIinit (word \fIlen\fR, const char *\fIstr\fR);
.br
GSStringPtr GIchange (GSStringPtr \fIorg\fR, word \fIlen\fR, const char *\fIstr\fR);
.br
void GIfree (GSStringPtr \fIstr\fR);
.sp 1
ResultBufPtr GOinit (word \fIlen\fR, const char *\fIstr\fR);
.br
ResultBufPtr GOchange (ResultBufPtr \fIorg\fR, word \fIlen\fR, const char *\fIstr\fR);
.br
void GOfree (ResultBufPtr \fIstr\fR);
.sp 1
GSStringPtr __C2GS (char *\fIstr\fR, GSStringPtr \fIgp\fR);
.br
GSStringPtr __C2GSMALLOC (const char *\fIstr\fR);
.br
char * __GS2C (char *\fIstr\fR, GSStringPtr \fIgp\fR);
.br
char * __GS2CMALLOC (GSStringPtr \fIgp\fR);
.SH 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:
.RS
.LP
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 
.IR "Can't Happen or /* NOTREACHED */ or Real Programs Dump Core" ,
by Ian Darwin and Geoff Collyer, USENIX Association Winter Conference,
Dallas 1985 Proceedings.
.LP
They take up memory regardless of whether or not it's used.
.LP
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.
.RE
.LP
These routines solve the above problems in a simple way.  There are now six
new struct pointers declared, 
.BR GSStringPtr ,
.BR GSStringHndl ,
.BR GSStringHndlPtr ,
.BR ResultBufPtr ,
.BR ResultBufHndl ,
and
.BR ResultBufHndlPtr .
These are dynamic counterparts to the
.BR 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.
.LP
Note that there is no
.BR GSString
or 
.BR 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.
.LP
.BR GIinit
.RS
.BR GSString s
must be allocated and initialized using the
.BR GIinit
(or
.BR GIchange )
routines.
On success, the
.BR length
field of the structure pointed to by
.BR GIinit
will be set to
.IR len ,
and the
.BR text
field will be
.IR len +1
bytes long.
The extra (last) byte in this field is provided so that it can be
used for a NULL terminating byte.
.LP
If
.IR str
is non-NULL, it's contents (which is assumed to be a NULL-terminated C
string) will be copied into the
.BR text
field, up to a maximum of
.IR len
bytes, and will be NULL terminated.
If
.BR str
is NULL, a NULL-terminating byte will be placed in both the first and
final byte positions in the
.BR text 
field.
On failure,
.BR GIinit
will return the NULL pointer.
.RE
.LP
.BR GIchange
.RS
The
.BR GIchange
routine is used to change the size of a GSString.  It is similar to
.BR GIinit
.RB ( GIinit
is implemented in terms of 
.BR GIchange ),
except that it takes an additional parameter,
.IR org ,
which is a 
.BR GSStringPtr
holding the result of a previous call to either
.BR GIinit
or 
.BR GIchange .
.LP
If
.IR org
is NULL, 
.BR GIchange
behaves exactly like
.BR GIinit .
If 
.IR org
is non-NULL, then the GSString pointed to by
.IR org 
will be copied into the returned result, and the memory pointed to by
.IR org
will no longer be usable.
Note that if
.IR len
is greater than the previous length of
.IR org 
and
.IR str
is NULL, the latter part of the
.BR text
field will be uninitialized, except that there will be a terminating NULL
byte at the end of the 
.BR text
field (as well as the original NULL-terminating byte at the end of
the old
.BR text
field).
.LP
On success,
.BR GIchange
returns the new GSString.  On failure it returns NULL and sets
.BR errno .
.LP
Note that if this call succeeds, the region pointed to by
.IR org
subsequently may not be legally referenced.  If the call fails,
.IR org
is unchanged.
.RE
.LP
.BR GIfree
.RS
.BR GIfree
is used to deallocate memory allocated with either
.BR GIinit 
or
.BR GIchange .
It is currently implemented as a macro.
.RE
.LP
.BR GOinit
.br
.BR GOchange
.RS
The behavior of 
.BR GOinit 
and
.BR GOchange
are similar to the routines
.BR GIinit
and
.BR GIchange ,
respectively, except that if
.IR str
is NULL, the
.BR bufString->length
and
.BR bufString->text
fields of the result will be unmodified, unless:
.RS
.LP
.IR org
is also NULL, in which case these fields are set to be the empty
string; or
.LP
.IR len
is less than the length of the GSString
.IR org ,
in which case the 
.BR bufString->length
is set to 
.IR len .
.LP
.RE
A terminating NULL byte will always be placed in the
last character of
.BR bufString->text .
.RE
.LP
.BR GOfree
.RS
.BR GOfree
is used to deallocate memory allocated with either
.BR GOinit 
or
.BR GOchange .
It is currently implemented as a macro.
.RE
.LP
.BR __C2GSMALLOC
.RS
.BR __C2GSMALLOC
takes a C-style string 
.I str
and returns a GSStringPtr pointing to a Class 1 GS/OS string containing
a copy of 
.IR str .
The returned GS/OS string will have an NULL-terminating extra byte in the 
.BR text
field.
Space allocated by this routine should be released with
.BR GIfree
when it is no longer required.
On failure the NULL pointer is returned.
.RE
.LP
.BR __C2GS
.RS
.BR __C2GS
converts a C string to a Class 1 GS/OS string, where
.IR gp
points to space for the result which is already allocated.
The required space for this routine is:
.nf
	sizeof(word) + strlen(\fIstr\fR) + 1
.fi
Failure to provide sufficient space may result in memory corruption;
.IR "this routine should be used with caution" .
If the C string is too long to fit in a GS/OS string, 
.BR __C2GS
returns NULL and sets
.BR errno .
.RE
.LP
.BR __GS2CMALLOC
.RS
.BR __GS2CMALLOC
is similar to
.BR __C2GSMALLOC ,
but the direction of conversion is reversed.
The result of 
.BR __GS2CMALLOC
will be a pointer to memory allocated by
.BR malloc (3)
and should be released with
.BR free (3)
when it is no longer required.
.RE
.LP
.BR __GS2C
.RS
.BR __GS2C
is similar to
.BR __C2GS ,
but the direction of conversion is reversed.
.BR __GS2C
expects the memory region pointed to by
.IR str
to be sufficiently large to hold the result (this should be at least
\fIgp\fB->length\fR + 1); if this is not so, then memory corruption may
occur.  
.BR __GS2C
always returns
.IR str .
.SH CAVEATS
Although these routines operate in similar ways, it is an error to mix
these routines.  For example, the
.BR bufString
field of a ResultBuf cannot be resized using
.BR GIchange ;
instead 
.BR GOchange 
must be used.
.SH AUTHOR
The GI and GO routines are based on code by
Soenke Behrens <s_behrens@emulex.com>.
.LP
The remaining routines
were reimplemented from spec by Devin Reade <gdr@gno.org>.
.SH HISTORY
The GI and GO routines first appeared in the 
.IR "GSString Library"
under slightly different names.
.LP
.BR __C2GSMALLOC ,
.BR __GS2CMALLOC ,
and
.BR __GS2C
first appeared in GNO v1.0.
.SH "SEE ALSO"
.I "GS/OS Reference Manual"