(gcrypt.info) Working with S-expressions

Info Catalog (gcrypt.info) Data types for S-expressions (gcrypt.info) S-expressions
 
 Working with S-expressions
 ==========================
 
 There are several functions to create an Libgcrypt S-expression object
 from its external representation or from a string template.  There is
 also a function to convert the internal representation back into one of
 the external formats:
 
  - Function: gcry_error_t gcry_sexp_new (gcry_sexp_t *R_SEXP,
           const void *BUFFER, size_t LENGTH, int AUTODETECT)
      This is the generic function to create an new S-expression object
      from its external representation in BUFFER of LENGTH bytes.  On
      success the result is stored at the address given by R_SEXP.  With
      AUTODETECT set to 0, the data in BUFFER is expected to be in
      canonized format, with AUTODETECT set to 1 the parses any of the
      defined external formats.  If BUFFER does not hold a valid
      S-expression an error code is returned and R_SEXP set to `NULL'.
      Note, that the caller is responsible for releasing the newly
      allocated S-expression using `gcry_sexp_release'.
 
  - Function: gcry_error_t gcry_sexp_create (gcry_sexp_t *R_SEXP,
           void *BUFFER, size_t LENGTH, int AUTODETECT,
           void (*FREEFNC)(void*))
      This function is identical to `gcry_sexp_new' but has an extra
      argument FREEFNC, which, when not set to `NULL', is expected to be
      a function to release the BUFFER; most likely the standard `free'
      function is used for this argument.  This has the effect of
      transferring the ownership of BUFFER to the created object in
      R_SEXP.  The advantage of using this function is that Libgcrypt
      might decide to directly use the provided buffer and thus avoid
      extra copying.
 
  - Function: gcry_error_t gcry_sexp_sscan (gcry_sexp_t *R_SEXP,
           size_t *ERROFF, const char *BUFFER, size_t LENGTH)
      This is another variant of the above functions.  It behaves nearly
      identical but provides an ERROFF argument which will receive the
      offset into the buffer where the parsing stopped on error.
 
  - Function: gcry_error_t gcry_sexp_build (gcry_sexp_t *R_SEXP,
           size_t *ERROFF, const char *FORMAT, ...)
      This function creates an internal S-expression from the string
      template FORMAT and stores it at the address of R_SEXP. If there
      is a parsing error, the function returns an appropriate error code
      and stores the offset into FORMAT where the parsing stopped in
      ERROFF.  The function supports a couple of printf-like formatting
      characters and expects arguments for some of these escape
      sequences right after FORMAT.  The following format characters are
      defined:
 
     `%m'
           The next argument is expected to be of type `gcry_mpi_t' and
           a copy of its value is inserted into the resulting
           S-expression.
 
     `%s'
           The next argument is expected to be of type `char *' and that
           string is inserted into the resulting S-expression.
 
     `%d'
           The next argument is expected to be of type `int' and its
           value ist inserted into the resulting S-expression.
 
     `%b'
           The next argument is expected to be of type `int' directly
           followed by an argument of type `char *'.  This represents a
           buffer of given length to be inserted into the resulting
           regular expression.
 
      No other format characters are defined and would return an error.
      Note, that the format character `%%' does not exists, because a
      percent sign is not a valid character in an S-expression.
 
  - Function: void gcry_sexp_release (gcry_sexp_t SEXP)
      Release the S-expression object SEXP.
 
 The next 2 functions are used to convert the internal representation
 back into a regular external S-expression format and to show the
 structure for debugging.
 
  - Function: size_t gcry_sexp_sprint (gcry_sexp_t SEXP, int MODE,
           char *BUFFER, size_t MAXLENGTH)
      Copies the S-expression object SEXP into BUFFER using the format
      specified in MODE.  MAXLENGTH must be set to the allocated length
      of BUFFER.  The function returns the actual length of valid bytes
      put into BUFFER or 0 if the provided buffer is too short.  Passing
      `NULL' for BUFFER returns the required length for BUFFER.  For
      convenience reasons an extra byte with value 0 is appended to the
      buffer.
 
      The following formats are supported:
 
     `GCRYSEXP_FMT_DEFAULT'
           Returns a convenient external S-expression representation.
 
     `GCRYSEXP_FMT_CANON'
           Return the S-expression in canonical format.
 
     `GCRYSEXP_FMT_BASE64'
           Not currently supported.
 
     `GCRYSEXP_FMT_ADVANCED'
           Returns the S-expression in advanced format.
 
  - Function: void gcry_sexp_dump (gcry_sexp_t SEXP)
      Dumps SEXP in a format suitable for debugging to Libgcrypt's
      logging stream.
 
 Often canonical encoding is used in the external representation.  The
 following function can be used to check for valid encoding and to learn
 the length of the S-expression"
 
  - Function: size_t gcry_sexp_canon_len (const unsigned char *BUFFER,
           size_t LENGTH, size_t *ERROFF, int *ERRCODE)
      Scan the canonical encoded BUFFER with implicit length values and
      return the actual length this S-expression uses.  For a valid
      S-expression it should never return 0.  If LENGTH is not 0, the
      maximum length to scan is given; this can be used for syntax
      checks of data passed from outside.  ERRCODE and ERROFF may both be
      passed as `NULL'.
 
 
 There are a couple of functions to parse S-expressions and retrieve
 elements:
 
  - Function: gcry_sexp_t gcry_sexp_find_token (const gcry_sexp_t LIST,
           const char *TOKEN, size_t TOKLEN)
      Scan the S-expression for a sublist with a type (the car of the
      list) matching the string TOKEN.  If TOKLEN is not 0, the token is
      assumed to be raw memory of this length.  The function returns a
      newly allocated S-expression consisting of the found sublist or
      `NULL' when not found.
 
  - Function: int gcry_sexp_length (const gcry_sexp_t LIST)
      Return the length of the LIST.  For a valid S-expression this
      should be at least 1.
 
  - Function: gcry_sexp_t gcry_sexp_nth (const gcry_sexp_t LIST,
           int NUMBER)
      Create and return a new S-expression from the element with index
      NUMBER in LIST.  Note that the first element has the index 0.  If
      there is no such element, `NULL' is returned.
 
  - Function: gcry_sexp_t gcry_sexp_car (const gcry_sexp_t LIST)
      Create and return a new S-expression from the first element in
      LIST; this called the "type" and should always exist and be a
      string. `NULL' is returned in case of a problem.
 
  - Function: gcry_sexp_t gcry_sexp_cdr (const gcry_sexp_t LIST)
      Create and return a new list form all elements except for the
      first one.  Note, that this function may return an invalid
      S-expression because it is not guaranteed, that the type exists
      and is a string.  However, for parsing a complex S-expression it
      might be useful for intermediate lists.  Returns `NULL' on error.
 
  - Function: const char * gcry_sexp_nth_data (const gcry_sexp_t LIST,
           int NUMBER, size_t *DATALEN)
      This function is used to get data from a LIST.  A pointer to the
      actual data with index NUMBER is returned and the length of this
      data will be stored to DATALEN.  If there is no data at the given
      index or the index represents another list, `NULL' is returned.
 
      Here is an example on how to extract and print the surname (Meier)
      from the S-expression `(Name Otto Meier (address Burgplatz 3))':
 
           size_t len;
           const char *name;
           
           name = gcry_sexp_nth_data (list, 2, &len);
           printf ("my name is %.*s\n", (int)len, name);
 
  - Function: gcry_mpi_t gcry_sexp_nth_mpi (gcry_sexp_t LIST,
           int NUMBER, int MPIFMT)
      This function is used to get and convert data from a LIST. This
      data is assumed to be an MPI stored in the format described by
      MPIFMT and returned as a standard Libgcrypt MPI.  The caller must
      release this returned value using `gcry_mpi_release'.  If there is
      no data at the given index, the index represents a list or the
      value can't be converted to an MPI, `NULL' is returned.
 
Info Catalog (gcrypt.info) Data types for S-expressions (gcrypt.info) S-expressions
automatically generated by info2html