fixup krb5_storage_truncate return value, add krb5_{store,ret}_data_xdr, doxygen

git-svn-id: svn://svn.h5l.se/heimdal/trunk/heimdal@24234 ec53bebd-3082-4978-b11e-865c3cabbd6b

lib/krb5/doxygen.c

@@ -75,6 +75,7 @@ RCSID("$Id$");
 /** @defgroup krb5_ticket Heimdal Kerberos 5 ticket functions */
 /** @defgroup krb5_pac Heimdal Kerberos 5 PAC handling functions */
 /** @defgroup krb5_v4compat Heimdal Kerberos 4 compatiblity functions */
+/** @defgroup krb5_storage Heimdal Kerberos 5 storage functions */
 /** @defgroup krb5_support Heimdal Kerberos 5 support functions */
 
 

lib/krb5/store.c

@@ -63,7 +63,7 @@ krb5_storage_clear_flags(krb5_storage *sp, krb5_flags flags)
  *
  * @return true if all the flags are set, false if not.
  *
- * @ingroup krb5_support
+ * @ingroup krb5_storage
  */
 
 krb5_boolean KRB5_LIB_FUNCTION
@@ -81,7 +81,7 @@ krb5_storage_is_flags(krb5_storage *sp, krb5_flags flags)
  * The byte order are: KRB5_STORAGE_BYTEORDER_BE,
  * KRB5_STORAGE_BYTEORDER_LE and KRB5_STORAGE_BYTEORDER_HOST.
  *
- * @ingroup krb5_support
+ * @ingroup krb5_storage
  */
 
 void KRB5_LIB_FUNCTION
@@ -94,7 +94,7 @@ krb5_storage_set_byteorder(krb5_storage *sp, krb5_flags byteorder)
 /**
  * Return the current byteorder for the buffer. See krb5_storage_set_byteorder() for the list or byte order contants.
  *
- * @ingroup krb5_support
+ * @ingroup krb5_storage
  */
 
 krb5_flags KRB5_LIB_FUNCTION
@@ -113,7 +113,7 @@ krb5_storage_get_byteorder(krb5_storage *sp)
  *
  * @return The new current offset
  *
- * @ingroup krb5_support
+ * @ingroup krb5_storage
  */
 
 off_t KRB5_LIB_FUNCTION
@@ -130,10 +130,10 @@ krb5_storage_seek(krb5_storage *sp, off_t offset, int whence)
  *
  * @return An Kerberos 5 error code.
  *
- * @ingroup krb5_support
+ * @ingroup krb5_storage
  */
 
-krb5_error_code KRB5_LIB_FUNCTION
+int KRB5_LIB_FUNCTION
 krb5_storage_truncate(krb5_storage *sp, off_t offset)
 {
     return (*sp->trunc)(sp, offset);
@@ -148,7 +148,7 @@ krb5_storage_truncate(krb5_storage *sp, off_t offset)
  *
  * @return The length of data read (can be shorter then len), or negative on error.
  *
- * @ingroup krb5_support
+ * @ingroup krb5_storage
  */
 
 krb5_ssize_t KRB5_LIB_FUNCTION
@@ -166,7 +166,7 @@ krb5_storage_read(krb5_storage *sp, void *buf, size_t len)
  *
  * @return The length of data written (can be shorter then len), or negative on error.
  *
- * @ingroup krb5_support
+ * @ingroup krb5_storage
  */
 
 krb5_ssize_t KRB5_LIB_FUNCTION
@@ -212,7 +212,7 @@ _krb5_get_int(void *buffer, unsigned long *value, size_t size)
  *
  * @return An Kerberos 5 error code.
  *
- * @ingroup krb5_support
+ * @ingroup krb5_storage
  */
 
 krb5_error_code KRB5_LIB_FUNCTION
@@ -437,6 +437,42 @@ krb5_store_data(krb5_storage *sp,
     return 0;
 }
 
+/**
+ * Store a XDR opaque from the storage (data padded up a 4 byte
+ * aligned offset).
+ *
+ * @param sp the storage buffer to write to
+ * @param data the buffer to store.
+ *
+ * @return 0 on success, a Kerberos 5 error code on failure.
+ *
+ * @ingroup krb5_storage
+ */
+
+krb5_error_code KRB5_LIB_FUNCTION
+krb5_store_data_xdr(krb5_storage *sp,
+		    krb5_data data)
+{
+    krb5_error_code ret;
+
+    ret = krb5_store_data(sp, data);
+    if (ret)
+	return ret;
+    if ((data.length % 4) != 0) {
+	static const char zero[4] = { 0, 0, 0, 0 };
+	size_t res;
+
+	res = 4 - (data.length % 4);
+	if (res != 4) {
+	    ret = sp->store(sp, zero, res);
+	    if(ret != res)
+		return (ret < 0)? errno : sp->eof_code;
+	}
+    }
+    return 0;
+}
+
+
 krb5_error_code KRB5_LIB_FUNCTION
 krb5_ret_data(krb5_storage *sp,
 	      krb5_data *data)
@@ -458,6 +494,41 @@ krb5_ret_data(krb5_storage *sp,
     return 0;
 }
 
+/**
+ * Parse a XDR opaque from the storage (data padded up a 4 byte
+ * aligned offset).
+ *
+ * @param sp the storage buffer to read from
+ * @param data the buffer to parse.
+ *
+ * @return 0 on success, a Kerberos 5 error code on failure.
+ *
+ * @ingroup krb5_storage
+ */
+
+krb5_error_code KRB5_LIB_FUNCTION
+krb5_ret_data_xdr(krb5_storage *sp,
+		  krb5_data *data)
+{
+    krb5_error_code ret;
+    ret = krb5_ret_data(sp, data);
+    if (ret)
+	return ret;
+
+    if ((data->length % 4) != 0) {
+	char buf[4];
+	size_t res;
+
+	res = 4 - (data->length % 4);
+	if (res != 4) {
+	    ret = sp->fetch(sp, buf, res);
+	    if(ret != res)
+		return (ret < 0)? errno : sp->eof_code;
+	}
+    }
+    return 0;
+}
+
 krb5_error_code KRB5_LIB_FUNCTION
 krb5_store_string(krb5_storage *sp, const char *s)
 {

lib/krb5/store_emem.c

@@ -137,6 +137,21 @@ emem_free(krb5_storage *sp)
     free(s->base);
 }
 
+/**
+ * Create a elastic (allocating) memory storage backend. Memory is
+ * allocated on demand. Free returned krb5_storage with
+ * krb5_storage_free().
+ *
+ * @return A krb5_storage on success, or NULL on out of memory error.
+ *
+ * @ingroup krb5_storage
+ *
+ * @sa krb5_storage_from_mem()
+ * @sa krb5_storage_from_readonly_mem()
+ * @sa krb5_storage_from_fd()
+ * @sa krb5_storage_from_data()
+ */
+
 krb5_storage * KRB5_LIB_FUNCTION
 krb5_storage_emem(void)
 {

lib/krb5/store_fd.c

@@ -60,10 +60,12 @@ fd_seek(krb5_storage * sp, off_t offset, int whence)
     return lseek(FD(sp), offset, whence);
 }
 
-static off_t
+static int
 fd_trunc(krb5_storage * sp, off_t offset)
 {
-    return ftruncate(FD(sp), offset);
+    if (ftruncate(FD(sp), offset) == -1)
+	return errno;
+    return 0;
 }
 
 static void
@@ -72,6 +74,19 @@ fd_free(krb5_storage * sp)
     close(FD(sp));
 }
 
+/**
+ * 
+ *
+ * @return A krb5_storage on success, or NULL on out of memory error.
+ *
+ * @ingroup krb5_storage
+ *
+ * @sa krb5_storage_from_emem()
+ * @sa krb5_storage_from_mem()
+ * @sa krb5_storage_from_readonly_mem()
+ * @sa krb5_storage_from_data()
+ */
+
 krb5_storage * KRB5_LIB_FUNCTION
 krb5_storage_from_fd(int fd)
 {

lib/krb5/store_mem.c

@@ -93,8 +93,8 @@ mem_seek(krb5_storage *sp, off_t offset, int whence)
     return s->ptr - s->base;
 }
 
-static ssize_t
+static int
-mem_trunc(krb5_storage *sp, size_t offset)
+mem_trunc(krb5_storage *sp, off_t offset)
 {
     mem_storage *s = (mem_storage*)sp->data;
     if(offset > s->size)
@@ -105,12 +105,25 @@ mem_trunc(krb5_storage *sp, size_t offset)
     return 0;
 }
 
-static krb5_error_code
+static int
 mem_no_trunc(krb5_storage *sp, off_t offset)
 {
     return EINVAL;
 }
 
+/**
+ * 
+ *
+ * @return A krb5_storage on success, or NULL on out of memory error.
+ *
+ * @ingroup krb5_storage
+ *
+ * @sa krb5_storage_from_emem()
+ * @sa krb5_storage_from_readonly_mem()
+ * @sa krb5_storage_from_data()
+ * @sa krb5_storage_from_fd()
+ */
+
 krb5_storage * KRB5_LIB_FUNCTION
 krb5_storage_from_mem(void *buf, size_t len)
 {
@@ -137,12 +150,38 @@ krb5_storage_from_mem(void *buf, size_t len)
     return sp;
 }
 
+/**
+ * 
+ *
+ * @return A krb5_storage on success, or NULL on out of memory error.
+ *
+ * @ingroup krb5_storage
+ *
+ * @sa krb5_storage_from_emem()
+ * @sa krb5_storage_from_mem()
+ * @sa krb5_storage_from_readonly_mem()
+ * @sa krb5_storage_from_fd()
+ */
+
 krb5_storage * KRB5_LIB_FUNCTION
 krb5_storage_from_data(krb5_data *data)
 {
     return krb5_storage_from_mem(data->data, data->length);
 }
 
+/**
+ * 
+ *
+ * @return A krb5_storage on success, or NULL on out of memory error.
+ *
+ * @ingroup krb5_storage
+ *
+ * @sa krb5_storage_from_emem()
+ * @sa krb5_storage_from_mem()
+ * @sa krb5_storage_from_data()
+ * @sa krb5_storage_from_fd()
+ */
+
 krb5_storage * KRB5_LIB_FUNCTION
 krb5_storage_from_readonly_mem(const void *buf, size_t len)
 {