diff options
author | Greg Hudson <ghudson@mit.edu> | 2014-07-02 12:03:54 -0400 |
---|---|---|
committer | Greg Hudson <ghudson@mit.edu> | 2014-07-30 12:11:38 -0400 |
commit | 651f3af251d172361a954f55f2d87561ae42c2d0 (patch) | |
tree | 318ba0d2fb735498350c373029319d4fa189e113 /src/include | |
parent | 346ad2b3c0b13ba5e34d8b7777196bdcd14ab64d (diff) | |
download | krb5-651f3af251d172361a954f55f2d87561ae42c2d0.zip krb5-651f3af251d172361a954f55f2d87561ae42c2d0.tar.gz krb5-651f3af251d172361a954f55f2d87561ae42c2d0.tar.bz2 |
Modify k5buf interfaces for easier use
Make struct k5buf less opaque and get rid of k5buf-int.h. Make it
easy to initialize a k5buf in an error state so that it can be freed
in a cleanup handler. Add a function k5_buf_status which returns 0 or
ENOMEM. Remove k5_buf_data and k5_buf_len. Rename k5_free_buf to
k5_buf_free. Adjust all callers to match.
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/k5-buf.h | 87 |
1 files changed, 26 insertions, 61 deletions
diff --git a/src/include/k5-buf.h b/src/include/k5-buf.h index da10fd9..f3207bd 100644 --- a/src/include/k5-buf.h +++ b/src/include/k5-buf.h @@ -27,62 +27,47 @@ #ifndef K5_BUF_H #define K5_BUF_H -#if defined(_MSDOS) || defined(_WIN32) -#include <win-mac.h> -#endif -#ifndef KRB5_CALLCONV -#define KRB5_CALLCONV -#define KRB5_CALLCONV_C -#endif - #include <stdarg.h> #include <string.h> -#ifndef _WIN32 -#include <unistd.h> -#endif /* * The k5buf module is intended to allow multi-step string construction in a * fixed or dynamic buffer without the need to check for a failure at each step * (and without aborting on malloc failure). If an allocation failure occurs - * or if the fixed buffer runs out of room, the error will be discovered when - * the caller retrieves the C string value or checks the length of the - * resulting buffer. + * or the fixed buffer runs out of room, the buffer will be set to an error + * state which can be detected with k5_buf_status. Data in a buffer is + * terminated with a zero byte so that it can be used as a C string. * - * k5buf structures are stack-allocated, but are intended to be opaque, so do - * not access the fields directly. This is a tool, not a way of life, so do - * not put k5buf structure pointers into the public API or into significant - * internal APIs. + * k5buf structures are usually stack-allocated. Do not put k5buf structure + * pointers into public APIs. It is okay to reference the data and len fields + * of a buffer (they will be NULL/0 if the buffer is in an error state), but do + * not change them. */ -/* - * We must define the k5buf structure here to allow stack allocation. The - * structure is intended to be opaque, so the fields have funny names. - */ +/* Buffer type values */ +enum k5buftype { K5BUF_ERROR, K5BUF_FIXED, K5BUF_DYNAMIC }; + struct k5buf { - int xx_buftype; - char *xx_data; - size_t xx_space; - size_t xx_len; + enum k5buftype buftype; + void *data; + size_t space; + size_t len; }; +#define EMPTY_K5BUF { K5BUF_ERROR } + /* Initialize a k5buf using a fixed-sized, existing buffer. SPACE must be * more than zero, or an assertion failure will result. */ void k5_buf_init_fixed(struct k5buf *buf, char *data, size_t space); -/* Initialize a k5buf using an internally allocated dynamic buffer. The - * buffer contents must be freed with k5_free_buf. */ +/* Initialize a k5buf using an internally allocated dynamic buffer. */ void k5_buf_init_dynamic(struct k5buf *buf); /* Add a C string to BUF. */ void k5_buf_add(struct k5buf *buf, const char *data); -/* - * Add a counted set of bytes to BUF. It is okay for DATA[0..LEN-1] - * to contain null bytes if you are prepared to deal with that in the - * output (use k5_buf_len to retrieve the length of the output). - */ -void k5_buf_add_len(struct k5buf *buf, const char *data, size_t len); +/* Add a counted series of bytes to BUF. */ +void k5_buf_add_len(struct k5buf *buf, const void *data, size_t len); /* Add sprintf-style formatted data to BUF. */ void k5_buf_add_fmt(struct k5buf *buf, const char *fmt, ...) @@ -99,36 +84,16 @@ void *k5_buf_get_space(struct k5buf *buf, size_t len); * length, or an assertion failure will result. */ void k5_buf_truncate(struct k5buf *buf, size_t len); -/* - * Retrieve the byte array value of BUF, or NULL if there has been an - * allocation failure or the fixed buffer ran out of room. - * - * The byte array will be a C string unless binary data was added with - * k5_buf_add_len; it will be null-terminated regardless. Modifying the byte - * array does not invalidate the buffer, as long as its length is not changed. - * - * For a fixed buffer, the return value will always be equal to the passed-in - * value of DATA at initialization time if it is not NULL. - * - * For a dynamic buffer, any buffer modification operation except - * k5_buf_truncate may invalidate the byte array address. - */ -char *k5_buf_data(struct k5buf *buf); - -/* - * Retrieve the length of BUF, or -1 if there has been an allocation failure or - * the fixed buffer ran out of room. The length is equal to - * strlen(k5_buf_data(buf)) unless binary data was added with k5_buf_add_len. - */ -ssize_t k5_buf_len(struct k5buf *buf); +/* Return ENOMEM if buf is in an error state, 0 otherwise. */ +int k5_buf_status(struct k5buf *buf); /* * Free the storage used in the dynamic buffer BUF. The caller may choose to - * take responsibility for freeing the return value of k5_buf_data instead of - * using this function. If BUF is a fixed buffer, an assertion failure will - * result. It is unnecessary (though harmless) to free a buffer after an error - * is detected; the storage will already have been freed in that case. + * take responsibility for freeing the data pointer instead of using this + * function. If BUF is a fixed buffer, an assertion failure will result. + * Freeing a buffer in the error state, a buffer initialized with EMPTY_K5BUF, + * or a zeroed k5buf structure is a no-op. */ -void k5_free_buf(struct k5buf *buf); +void k5_buf_free(struct k5buf *buf); #endif /* K5_BUF_H */ |