Purdue University

Identity and Access Management

IAMO Home > Services > Web Page / Application Authentication > I2A2 >

Man Page for puidnetd_unpk

Introduction to Library Functions                puidnetd_unpk(3)

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

SYNOPSIS
     #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
     cont);

DESCRIPTION
     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.

     puidnetd_allocup();
          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_ENOMEM.

     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_clrunp().

     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.)

RETURN VALUES
     puidnetd_allocup()
         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:

         PUIDNETD_ENOMEM
             indicates no malloc(3) space available.

     puidnetd_ckcd()
         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:

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

SunOS 5.8                 Last change:                          2

Introduction to Library Functions                puidnetd_unpk(3)

     puidnetd_clrunp()
         has a void return value.

     puidnetd_freeup()
         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:

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

     puidnetd_unpfld()
         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
         puidnetd_errno:

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

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

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

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

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

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

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

         PUIDNETD_EIAUTHACLPM

SunOS 5.8                 Last change:                          3

Introduction to Library Functions                puidnetd_unpk(3)

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

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

         PUIDNETD_EICD
             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.

         PUIDNETD_EILLB64CH
             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.)

         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).

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

         PUIDNETD_EILLPUID
             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.)

         PUIDNETD_EILLTM
             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.

         PUIDNETD_EINTERNAL
             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)

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

         PUIDNETD_ENOCMD
             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.

         PUIDNETD_ENOMEM
             indicates no malloc(3) space is available.

         PUIDNETD_ERECFLD
             Illegal record field.

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

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

UNPACK STRUCTURE MANAGEMENT
     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.

EXAMPLES
     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",
                    puidnetd_strerror(puidnetd_errno));
              exit(1);
          }
          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",
                         puidnetd_strerror(puidnetd_errno));
                              (void) puidnetd_clrunp(u, 0);
                    exit(1);
               }
          }
          /* Process the unpacked message elements via references
           * like u->nu_cmd for accessing the command and reply
           * character. */
          (void) puidnetd_freeup(u);

FILES
     puidnetd.h
          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-
          tion.

AUTHOR
     The puidnetd_unpk function family was written by Victor A.
     Abell <abe@purdue.edu>.

SEE ALSO
     puidnetd_strerror(3), puidnetd(4).

SunOS 5.8                 Last change:                          6