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
       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, 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