Connect to the Purdue Home Page

Purdue University

Identity and Access Management

Introduction to Library Functions                puidnetd_unpk(3)

     puidnetd_allocup(), puidnetd_ckcd(), puidnetd_clrunp(),
     puidnetd_freeup(), puidnetd_unpfld() - PUIDNETD protocol
     message functions

     #include "puidnetd.h"

     puidnetd_unpk_t * puidnetd_allocup(void);

     int puidnetd_ckcd(char *pc, size_t pl, puid_t pb);

     void puidnetd_clrunp(puidnetd_unpk_t *unpk, int disp);

     int puidnetd_freeup(puidnetd_unpk_t *unpk);

     int puidnetd_unpfld(char *msg, puidnetd_unpk_t *unpk, int

     The puidnetd_unpk family of functions provides services for
     managing incoming PUIDNETD protocol messages.  See puid-
     netd(4) for a description of the PUIDNETD protocol and its
     messages.  See the puidnetd.h header file for a definition
     of related structures.  See puidnetd_strerror(3) for more
     information about handling PUIDNETD protocol errors and the
     puidnetd_errno external variable.

          allocates a properly initialized puidnetd_unpk_t struc-
          ture and returns its address.  If no structure can be
          made available, a NULL pointer is returned and the the
          value of the external variable puidnetd_errno is set to

     puidnetd_ckcd(char *pc, size_t pl, puid_t pb);
          checks the Luhn check digit of a PUID specified in
          character or binary form.

          The PUID is specified in character form by supplying a
          pointer to it in *cp.  If the pl argument is non-zero,
          it specifies the length of the PUID to which *cp
          points.  If pl is zero, the function considers charac-
          ters up to a NUL ('\0') as part of the PUID.

          The PUID is assumed to have been supplied in binary
          form in the pb argument if the *cp argument is NULL.

          The function returns zero if the PUID's check digit is
          valid; if invalid, the non-zero PUIDNETD_ECKDF error
          code is returned and also stored in the puidnetd_errno
          external variable.  (See puidnetd(4) for a description

SunOS 5.8                 Last change:                          1

Introduction to Library Functions                puidnetd_unpk(3)

          of the PUIDNETD protocol and its messages.)

     puidnetd_clrunp(puidnetd_unpk_t *unpk, int disp);
          clears a previously allocated puidnetd_unpk_t structure
          whose address is supplied in the *unpk argument.  The
          disp argument defines what is to be done with the *unpk
          structure after it has been cleared: a value of 0
          (zero) indicates that only clearing is required; a
          value of 1 (one) indicates the memory occupied by the
          structure is to be freed via a call to the malloc(3)
          library's free(3) function.

     puidnetd_freeup(puidnetd_unpk_t *unpk);
          frees a puidnetd_unpk_t structure, previously allocated
          by puidnetd_allocup(), for future use.  The freed
          structure is cleared via a disp=0 call to

     puidnetd_unpfld(char *msg, puidnetd_unpk_t *unpk, int cont);
          unpacks a PUIDNETD protocol message.  The *msg argument
          points to the NUL ('\0') terminated PUIDNETD protocol
          message, stripped of its ending '\r' and '\n' charac-
          ters.  The *unpk argument points to a puidnetd_unpk_t
          structure, initialized or containing information from a
          previously continued message.  The cont argument indi-
          cates the current state of *unpk and the expected con-
          tents of *msg.  If cont is zero, then *msg is expected
          to point to the beginning of a new message sequence;
          non-zero, to the beginning of a continued message of a
          sequence begun by some previous message.  (The
          puidnetd_unpk() return value indicates when a message
          is continued.)

         returns a pointer to an allocated structure, or NULL if
         none could be allocated.  The external variable
         puidnetd_errno will explain the allocation failure with
         one of these codes, defined in puidnetd.h:

             indicates no malloc(3) space available.

         returns zero if the check digit is valid.  If the check
         digit is not valid this error code is returned in the
         external puidnetd_errno variable:

             signals a PUID check digit error:  the last digit of
             the PUID, a Luhn algorithm check digit, is

SunOS 5.8                 Last change:                          2

Introduction to Library Functions                puidnetd_unpk(3)

         has a void return value.

         returns 0 (zero) if the addressed puidnetd_unpk_t struc-
         ture was freed; otherwise it returns the non-zero value
         also found in the external variable puidnetd_errno,
         representing one of these conditions:

             indicates no puidnetd_unpk_t structure with an
             address matching the *unpk argument was located.

         returns 1 (one), if the message was unpacked without
         error and is continued; 0 (zero), if the message was
         unpacked without error and is not continued; or -1
         (minus 1), if an error was detected as elaborated in the
         following values of the external variable

             indicates an authentication DBM ACL record that
             isn't properly terminated.

             indicates an authentication DBM realm record that
             isn't properly terminated.

             signals a PUID check digit error:  the last digit of
             the PUID, a Luhn algorithm check digit, is

             indicates a continuation record was encountered when
             one wasn't expected, or a continuation was expected
             but not found.

             Duplicate field encountered. Most fields may only be
             entered once, e.g., the PUID.

             indicates a field is too short; probably the field
             lacks a terminator character.

             indicates a field is too long.  Fields are limited
             to PUIDNETD_MAXFLDL, as defined in puidnetd.h.


SunOS 5.8                 Last change:                          3

Introduction to Library Functions                puidnetd_unpk(3)

             indicates an authentication DBM ACL record with an
             invalid permission mask.

             indicates an illegal authentication DBM ACL record
             (illegal operation type, or a missing PUID_MSGTERM).

             Illegal client data. Certain types of
             PUIDNETD_DATA_* fields are restricted for use in
             internal communications between the netd and the DBM
             and may not be submitted by the client.

             A field that requires a base-64 string contained a
             character not in the base-64 alphabet ([a-zA-Z0-
             9/=]). (See also PUIDNETD_EILLCH.)

             indicates a field contains an illegal character.
             Fields may contain only ASCII printable characters.
             (See isprint(3).)  Some fields have further restric-
             tions (see PUIDNETD_EILLB64CH).

             indicates a field lacks a PUIDNETD_MSGTERM field
             terminator character.  (PUIDNETD_MSGTERM is defined
             in puidnetd.h.)

             indicates a PUID value that couldn't be converted to
             internal form because it was too long, less than
             MIN_PUID but not PUID_NOBODY, or greater than
             MAX_PUID. (If the PUID fails the check digit test,
             PUIDNETD_ECKDF is returned.)

             Illegal time value.  Time values are composed of a
             prefix, and an optional ".", and a suffix.  The pre-
             fix is a string representation of the time in
             seconds since 00:00:00 UTC, January 1, 1970.  The
             suffix is a serial number used to disambiguate oth-
             erwise identical times.  PUIDNETD_EILLTM is returned
             if the prefix fails conversion by strtoul(3c), or
             the converted value of the prefix equals ULONG_MAX.
             PUIDNETD_EILLTM is also returned when the optional
             suffix is included and the suffix value fails
             conversion or is greater than INT_MAX.

             indicates an internal (coding) error; this should
             never appear.  If it does, report it to the AUTHOR.

SunOS 5.8                 Last change:                          4

Introduction to Library Functions                puidnetd_unpk(3)

             indicates the supplied message is too short.  This
             indicates an improperly terminated message.

             indicates a message without a puidnetd protocol com-
             mand. Since the command is the first character of a
             message, this implies a message that is too short.

             indicates no malloc(3) space is available.

             Illegal record field.

             Unknown data type. During parsing, puid_unpfld()
             encountered a data field not enumerated in the
             PUIDNETD_DATA_* definitions.

             indicates no puidnetd_unpk_t structure with the sup-
             plied address could be located.

     Because PUIDNETD protocol messages can be continued, the
     contents of the puidnetd_unpk_t structure, addressed in the
     *unpk argument to puidnetd_unpfld(3), are important.

     If the structure is allocated with the puidnetd_allocup()
     function and freed with the puidnetd_freeup() function, the
     user of puidnetd_unpfld() generally need do no more.

     However, if the user of puidnetd_unpfld() allocates a
     private copy of a puidnetd_unpk_t structure, it should be
     allocated with the malloc(3) library's calloc(3) function,
     or cleared with the memset(3) function before being supplied
     to puidnetd_unpfld().

     The user of puidnetd_allocup() and puidnetd_unpfld() should
     use puidnetd_clrunp() when finished with a puidnetd_unpk_t
     that is to be subsequently reused.

     The following example allocates a puidnetd_unpk_t structure,
     unpacks a message to it, and frees the structure.

          #include "puidnetd.h"

          int cont, pcont;
          char *msg;
          puidnetd_unpk_t *u;

SunOS 5.8                 Last change:                          5

Introduction to Library Functions                puidnetd_unpk(3)

          if (!(u = puidnetd_allocup())) {
               (void) fprintf(stderr, "allocup: %s\n",
          for (cont = 1, pcont = 0; cont; pcont = cont) {
               /* Acquire a message string -- e.g., via fgets(),
                * -- strip the ending '\r' and '\n' and NUL-
                * terminate it. */

               if ((cont = puidnetd_unpfld(msg, u, pcont)) < 0) {
                    (void) fprintf(stderr, "unpfld: %s\n",
                              (void) puidnetd_clrunp(u, 0);
          /* Process the unpacked message elements via references
           * like u->nu_cmd for accessing the command and reply
           * character. */
          (void) puidnetd_freeup(u);

          is the header file for the PUIDNETD protocol.  It
          defines the puidnetd_unpk_t structure, related struc-
          tures, command characters, reply characters, field
          identification characters, the field terminator charac-
          ter, limits, error codes, and other related informa-

     The puidnetd_unpk function family was written by Victor A.
     Abell <>.

     puidnetd_strerror(3), puidnetd(4).

SunOS 5.8                 Last change:                          6


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.