.\" 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 .br #include .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 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 . .LP The remaining routines were reimplemented from spec by Devin Reade . .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"