NAME

       gd_fragment_namespace  —  report  or  change the root namespace of a fragment of a dirfile
       database

SYNOPSIS

       #include <getdata.h>

       const char *gd_fragment_namespace(DIRFILE *dirfile, int fragment_index, char
              *new_namespace);

DESCRIPTION

       The gd_fragment_namespace() function can be used to update and/or query the root namespace
       of a fragment in the dirfile(5) database specified by dirfile.

       If new_namespace is NULL, then the current root  namespace  of  the  fragment  indexed  by
       fragment_index  is  returned.   If  new_namespace  is non-NULL, then the root namespace is
       first changed to the string  provided  before  being  reported.   The  new  namespace  may
       optionally contain a single, trailing dot (.).  To remove an existing root namespace, pass
       a pointer to the empty string ("") as new_namespace.

       The root namespace of the root format file (the one indexed by fragment_index=0)  may  not
       be changed.  It is always the empty string.

       The  dirfile argument must point to a valid DIRFILE object previously created by a call to
       gd_open(3).

RETURN VALUE

       Upon successful completion, gd_fragment_namespace() returns a non-NULL pointer to a  read-
       only string containing the current root namespace of the fragment specified.  This will be
       a copy of the string new_namespace, if that parameter was  non-NULL.   If  the  fragment's
       root namespace is empty, a pointer to the empty string ("") will be returned.

       On error, this function returns NULL and sets the dirfile error to a non-zero error value.
       Possible dirfile error values are:

       GD_E_ACCMODE
               The dirfile was opened read-only.

       GD_E_ALLOC
               A memory allocation error occurred.

       GD_E_BAD_CODE
               The supplied new_fragment was not a valid namespace.

       GD_E_BAD_DIRFILE
               The supplied dirfile was invalid.

       GD_E_BAD_INDEX
               The supplied index was out of range.  This error  will  also  be  returned  if  an
               attempt   is   made  to  change  the  root  namespace  of  the  root  format  file
               (fragment_index zero).

       GD_E_DUPLICATE
               Attempting to change the root namespace resulted in a duplicated field definition.

       GD_E_PROTECTED
               The protection level of the specified fragment prohibits metadata changes.

       The dirfile error may be retrieved by calling gd_error(3).  A descriptive error string for
       the last error encountered can be obtained from a call to gd_error_string(3).

HISTORY

       The gd_fragment_namespace() function appeared in GetData-0.10.0.

SEE ALSO

       gd_alter_affixes(3), gd_include_ns(3), gd_open(3), dirfile(5), dirfile-format(5)