mirror of
https://github.com/GnoConsortium/gno.git
synced 2024-09-11 14:54:54 +00:00
341 lines
7.6 KiB
Groff
341 lines
7.6 KiB
Groff
.\" Man page by Devin Reade
|
|
.\"
|
|
.\" $Id: GSString.3,v 1.1 1997/02/27 07:32:20 gdr 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@myrias.com>.
|
|
.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"
|