Connect to the Purdue Home Page

Purdue University

Identity and Access Management

Introduction to Library Functions              puidnetdz_asmch(3)

     puidnetdz_asmch() - assemble PUIDNETD protocol authorization
     characteristics structures

     #include "puidnetd.h"

     int puidnetdz_asmch(
          char *str, size_t len, puidnetdz_chasm_t **ch, int nch

     The puidnetdz_asmch() function assembles authorization
     characteristics structures from an external protocol string.
     (The 'z' in its name stands for authoriZation.)

     Authorization characteristics are the mechanism for indicat-
     ing relationships associated with PUIDs (Purdue University
     IDentification numbers).  PUID authorization characteristics
     are stored in an authorization data base, controlled by an
     authorization DBM (Data Base Manager) of the Purdue I2A2
     (Infrastructure for Identification, Authentication, and
     Authorization) system, and may be accessed via network dae-
     mons.  See puidnetd(4) for more information on the network
     daemons and a discussion of their external protocol.

     The puidnetdz_asmch() function has these arguments:

         * str
             addresses the input string.  See the CHARACTERISTICS
             STRINGS section of this document for their descrip-

         len supplies the length of *str.

             addresses a variable where puidnetdz_asmch() will
             return the address of a statically allocated array
             of puidnetd_chasm_t structures.

         *n  addresses an integer variable where
             puidnetdz_asmch() will return a count of the number
             of puidnetd_chasm_t structures in **ch.

     The puidnetd_chasm_t structure is defined in puidnetd.h.

     Authorization characteristics strings consist of one or more
     clauses, separated by commas, that define authorization
     characteristics values.  There are three types of fields
     whose defining type codes may be found as PUIDNETDZ_CHTY_*
     symbols in puidnetd.h.  A null clause - e.g., one with

SunOS 5.8                 Last change:                          1

Introduction to Library Functions              puidnetdz_asmch(3)

     nothing in it, like ",," - is ignored.

         defines "Basic WorD" characteristics.  These are charac-
         teristics represented by single bits in an internal word
         array, since their definitions are common and general.
         Values following this type code are in hexadecimal; when
         there are multiple basic characteristic words, they are
         separated with the vertical bar ('|') character.  (See
         the PUIDNETDZ_CHTY_BCWORDS definition in puidnetd.h to
         determine how many words there are; currently there is

         In a hexadecimal value, the power of given bit defines a
         characteristic whose value is the power of two for the
         bit - e.g., characteristic three occupies the 2**3 posi-
         tion; fifteen, 2**15.  Here's an example of a basic word
         characteristics definition for characteristics two,
         three, and four:


         is an internal type code that never appears in external
         protocol strings.

         defines "global" characteristics.  Global characteris-
         tics are defined by official data sources and are
         updated daily.  A characteristic clause that begins with
         a decimal digit is assumed to be global.  Here's the
         basic word definition of the previous example, coupled
         with a clause for global characteristic 1234:


         That could be represented more tersely without the 'g'


         defines "private" characteristics.  Private characteris-
         tics are usually temporary ones, assigned immediately
         after an authorization record has been created for a
         PUID, and before the characteristic can be generated by
         official records.  For example, a new employee might be
         given a private characteristic noting employment, but
         official records won't show employment for some inter-

         When a global characteristic, matching a private one,

SunOS 5.8                 Last change:                          2

Introduction to Library Functions              puidnetdz_asmch(3)

         appears during a daily update, the private one is
         erased.  Private characteristics may occasionally be
         expired at the discretion of the I2A2 administrator.

         Here's an example that: sets basic word bits two, three,
         and four; has a null characteristic clause that
         puidnetdz_asmch() ignores; sets global characteristic
         1234; and sets private characteristic 5678.


     Additional information on definitions for and descriptions
     of authorization characteristics strings may be found in

     The puidnetdz_asmch() function returns 0 if characteristics
     were assembled without error.  Otherwise it returns a
     non-zero PUIDNETD error code that may also be found in the
     puidnetd_errno external variable.  These errors may be

          indicates that an illegal or ill-formed creator PUID or
          creation time is associated with a characteristic in
          the input string.

          indicates a general format error in the input string.

          indicates there is an illegal characteristics type in
          the input string.  Legal characteristics types are
          defined by the PUIDNETDZ_CHTY_* symbol definitions in

          indicates a characteristics value that is too large or
          too small.  An illegal value specified after a
          PUIDNETDZ_CHTY_BWD type is either unspecified or too
          large for the word arrays.

          An illegal value of any other type must be greater than
          or equal to zero and less than or equal to
          PUIDNETDZ_MAXCH.  PUIDNETDZ_MAXCH is defined in

          indicates that the puidnetdz_asmch() function could not
          allocate memory with calloc(3) or malloc(3).

SunOS 5.8                 Last change:                          3

Introduction to Library Functions              puidnetdz_asmch(3)

     The puidnetd_errno external variable is defined in the
     puidnetd.h header file.

     The following example unpacks the string "w1f,p21,g32,44" to
     four puidnetdz_chasm_t structures.

          #include "puidnetd.h"

          puidnetdz_chasm_t *c;
          int n;
          char *str = "w1f,p21,g32,44";

          if (puidnetdz_asmch(str, strlen(str), &c, &n)) {
               /* Process puidnetd_errno. */
          /* Process the n (4) puidnetdz_chasm_t structures
           * in c[]. */

     The puidnetdz_asmch() function was written by Victor A.
     Abell <>.

     puidnetd_strerror(3), puidnetd(4).

SunOS 5.8                 Last change:                          4

Feedback | Contact Purdue
Maintained by: IAMO Team

Purdue University, West Lafayette, IN 47907, (765) 494-4600
© 2010 - 2013 Purdue University | An equal access/equal opportunity university | Copyright Complaints
If you have trouble accessing this page because of a disability, please contact the CSC at or (765) 494-4000.