From b04c7fe6184af5fb9d51008c12e785de7c97a0ee Mon Sep 17 00:00:00 2001 From: Pekka Riikonen Date: Sun, 29 Jul 2007 19:04:35 +0000 Subject: [PATCH] Header comment changes. --- lib/silcutil/silcasync.h | 2 +- lib/silcutil/silcbase64.c | 4 +++ lib/silcutil/silcbase64.h | 7 ++--- lib/silcutil/silcbuffer.h | 50 +++++++++++++++++++++--------------- lib/silcutil/silcbuffmt.h | 22 +++++++++------- lib/silcutil/silccond.h | 3 ++- lib/silcutil/silcdlist.h | 3 ++- lib/silcutil/silcenv.h | 2 +- lib/silcutil/silcfdstream.h | 12 +++++---- lib/silcutil/silcfsm.h | 6 +++-- lib/silcutil/silchashtable.h | 2 +- lib/silcutil/silcmime.h | 6 +++-- 12 files changed, 72 insertions(+), 47 deletions(-) diff --git a/lib/silcutil/silcasync.h b/lib/silcutil/silcasync.h index 0cc2190e..6e746983 100644 --- a/lib/silcutil/silcasync.h +++ b/lib/silcutil/silcasync.h @@ -278,7 +278,7 @@ SilcAsyncOperation silc_async_alloc(SilcAsyncOperationAbort abort_cb, * silc_async_abort. Since this use pre-allocated context, the function * silc_async_free need not be called. This function is equivalent * to silc_async_alloc except this does not allocate any memory. The `op' - * needs not be uninitialized. + * needs not be uninitialized. This returns always TRUE. * * If the `pause_cb' is provided then the upper layer may also halt and * then later resume the execution of the operation, by calling the diff --git a/lib/silcutil/silcbase64.c b/lib/silcutil/silcbase64.c index c5c4242e..441ccbc8 100644 --- a/lib/silcutil/silcbase64.c +++ b/lib/silcutil/silcbase64.c @@ -36,6 +36,8 @@ char *silc_base64_encode(SilcStack stack, unsigned char *data, SilcUInt32 len) j = 0; pem = silc_scalloc(stack, ((len * 8 + 5) / 6) + 5, sizeof(*pem)); + if (!pem) + return NULL; for (i = 0; i < len; i++) { c = data[i]; @@ -127,6 +129,8 @@ unsigned char *silc_base64_decode(SilcStack stack, len = base64_len; data = silc_scalloc(stack, ((len * 6) / 8), sizeof(*data)); + if (!data) + return NULL; for (i = 0; i < len; i++) { c = base64[i]; diff --git a/lib/silcutil/silcbase64.h b/lib/silcutil/silcbase64.h index e060d4d7..98effa13 100644 --- a/lib/silcutil/silcbase64.h +++ b/lib/silcutil/silcbase64.h @@ -38,7 +38,7 @@ * DESCRIPTION * * Encodes data into Base 64 (PEM) encoding. Returns NULL terminated - * Base 64 encoded data string. + * Base 64 encoded data string. Returns NULL if system is out of memory. * * If `stack' is non-NULL the returned buffer is allocated from `stack'. * @@ -55,7 +55,7 @@ char *silc_base64_encode(SilcStack stack, unsigned char *data, SilcUInt32 len); * DESCRIPTION * * Same as silc_base64_encode() but puts newline ('\n') every 72 - * characters. + * characters. Returns NULL if system is out of memory. * * If `stack' is non-NULL the returned buffer is allocated from `stack'. * @@ -74,7 +74,8 @@ char *silc_base64_encode_file(SilcStack stack, * * DESCRIPTION * - * Decodes Base 64 (PEM) into data. Returns the decoded data. + * Decodes Base 64 (PEM) into data. Returns the decoded data. Returns + * NULL if the data is not valid Base 64 encoded data. * * If `stack' is non-NULL the returned buffer is allocated from `stack'. * diff --git a/lib/silcutil/silcbuffer.h b/lib/silcutil/silcbuffer.h index d98877bf..0a249cb0 100644 --- a/lib/silcutil/silcbuffer.h +++ b/lib/silcutil/silcbuffer.h @@ -238,7 +238,8 @@ SilcUInt32 silc_buffer_taillen(SilcBuffer x) * * DESCRIPTION * - * Allocates new SilcBuffer and returns it. Returns NULL on error. + * Allocates new SilcBuffer and returns it. Returns NULL if system is + * out of memory. * ***/ @@ -276,7 +277,8 @@ SilcBuffer silc_buffer_alloc(SilcUInt32 len) * * DESCRIPTION * - * Allocates new SilcBuffer and returns it. + * Allocates new SilcBuffer and returns it. Returns NULL if system is + * out of memory. * * This routine use SilcStack are memory source. If `stack' is NULL * reverts back to normal allocating routine. @@ -503,7 +505,8 @@ void silc_buffer_set(SilcBuffer sb, unsigned char *data, SilcUInt32 data_len) * * Pulls current data area towards end. The length of the currently * valid data area is also decremented. Returns pointer to the data - * area before pulling. Returns NULL on error. + * area before pulling. Returns NULL if the pull would lead to buffer + * overflow or would go beyond the valid data area. * * EXAMPLE * @@ -548,7 +551,8 @@ unsigned char *silc_buffer_pull(SilcBuffer sb, SilcUInt32 len) * * Pushes current data area towards beginning. Length of the currently * valid data area is also incremented. Returns a pointer to the - * data area before pushing. Returns NULL on error. + * data area before pushing. Returns NULL if the push would lead to + * buffer underflow or would go under the valid data area. * * EXAMPLE * @@ -593,7 +597,7 @@ unsigned char *silc_buffer_push(SilcBuffer sb, SilcUInt32 len) * * Pulls current tail section towards end. Length of the current valid * data area is also incremented. Returns a pointer to the data area - * before pulling. Returns NULL on error. + * before pulling. Returns NULL if the pull would lead to buffer overflow. * * EXAMPLE * @@ -638,7 +642,8 @@ unsigned char *silc_buffer_pull_tail(SilcBuffer sb, SilcUInt32 len) * * Pushes current tail section towards beginning. Length of the current * valid data area is also decremented. Returns a pointer to the - * tail section before pushing. Returns NULL on error. + * tail section before pushing. Returns NULL if the push would lead to + * buffer underflow or go under valid tail area. * * EXAMPLE * @@ -684,7 +689,8 @@ unsigned char *silc_buffer_push_tail(SilcBuffer sb, SilcUInt32 len) * DESCRIPTION * * Puts data at the head of the buffer. Returns pointer to the copied - * data area. Returns NULL on error. + * data area. Returns NULL if the data is longer that the current head + * area. * * EXAMPLE * @@ -724,7 +730,8 @@ unsigned char *silc_buffer_put_head(SilcBuffer sb, * DESCRIPTION * * Puts data at the start of the valid data area. Returns a pointer - * to the copied data area. Returns NULL on error. + * to the copied data area. Returns NULL if the data is longer than the + * current data area. * * EXAMPLE * @@ -764,7 +771,8 @@ unsigned char *silc_buffer_put(SilcBuffer sb, * DESCRIPTION * * Puts data at the tail of the buffer. Returns pointer to the copied - * data area. Returns NULL on error. + * data area. Returns NULL if the data is longer than the current tail + * area. * * EXAMPLE * @@ -803,7 +811,7 @@ unsigned char *silc_buffer_put_tail(SilcBuffer sb, * * Allocates `len' bytes size buffer and moves the tail area automatically * `len' bytes so that the buffer is ready to use without calling the - * silc_buffer_pull_tail. Returns NULL on error. + * silc_buffer_pull_tail. Returns NULL if system is out of memory. * ***/ @@ -828,7 +836,7 @@ SilcBuffer silc_buffer_alloc_size(SilcUInt32 len) * * Allocates `len' bytes size buffer and moves the tail area automatically * `len' bytes so that the buffer is ready to use without calling the - * silc_buffer_pull_tail. + * silc_buffer_pull_tail. Returns NULL if system is out of memory. * * This routine use SilcStack are memory source. If `stack' is NULL * reverts back to normal allocating routine. @@ -943,7 +951,7 @@ void silc_buffer_end(SilcBuffer sb) * * Generates copy of a SilcBuffer. This copies everything inside the * currently valid data area, nothing more. Use silc_buffer_clone to - * copy entire buffer. Returns NULL on error. + * copy entire buffer. Returns NULL if system is out of memory. * ***/ @@ -971,7 +979,7 @@ SilcBuffer silc_buffer_copy(SilcBuffer sb) * * Generates copy of a SilcBuffer. This copies everything inside the * currently valid data area, nothing more. Use silc_buffer_clone to - * copy entire buffer. + * copy entire buffer. Returns NULL if system is out of memory. * * This routine use SilcStack are memory source. If `stack' is NULL * reverts back to normal allocating routine. @@ -1005,7 +1013,7 @@ SilcBuffer silc_buffer_scopy(SilcStack stack, SilcBuffer sb) * * Clones SilcBuffer. This generates new SilcBuffer and copies * everything from the source buffer. The result is exact clone of - * the original buffer. Returns NULL on error. + * the original buffer. Returns NULL if system is out of memory. * ***/ @@ -1035,7 +1043,7 @@ SilcBuffer silc_buffer_clone(SilcBuffer sb) * * Clones SilcBuffer. This generates new SilcBuffer and copies * everything from the source buffer. The result is exact clone of - * the original buffer. + * the original buffer. Returns NULL if system is out of memory. * * This routine use SilcStack are memory source. If `stack' is NULL * reverts back to normal allocating routine. @@ -1072,7 +1080,7 @@ SilcBuffer silc_buffer_sclone(SilcStack stack, SilcBuffer sb) * Reallocates buffer. Old data is saved into the new buffer. The buffer * is exact clone of the old one except that there is now more space * at the end of buffer. This always returns the same `sb' unless `sb' - * was NULL. Returns NULL on error. + * was NULL. Returns NULL if system is out of memory. * ***/ @@ -1113,7 +1121,7 @@ SilcBuffer silc_buffer_realloc(SilcBuffer sb, SilcUInt32 newsize) * * Reallocates buffer. Old data is saved into the new buffer. The buffer * is exact clone of the old one except that there is now more space - * at the end of buffer. + * at the end of buffer. Returns NULL if system is out of memory. * * This routine use SilcStack are memory source. If `stack' is NULL * reverts back to normal allocating routine. @@ -1171,7 +1179,7 @@ SilcBuffer silc_buffer_srealloc(SilcStack stack, * * Same as silc_buffer_realloc but moves moves the tail area * automatically so that the buffer is ready to use without calling the - * silc_buffer_pull_tail. Returns NULL on error. + * silc_buffer_pull_tail. Returns NULL if system is out of memory. * ***/ @@ -1197,7 +1205,7 @@ SilcBuffer silc_buffer_realloc_size(SilcBuffer sb, SilcUInt32 newsize) * * Same as silc_buffer_srealloc but moves moves the tail area * automatically so that the buffer is ready to use without calling the - * silc_buffer_pull_tail. + * silc_buffer_pull_tail. Returns NULL if system is out of memory. * * This routine use SilcStack are memory source. If `stack' is NULL * reverts back to normal allocating routine. @@ -1233,7 +1241,7 @@ SilcBuffer silc_buffer_srealloc_size(SilcStack stack, * is at least the size of `size'. If there is more space than `size' * in the data area this does not do anything. If there is enough * space in the tail area this merely moves the tail area to reveal - * the extra space. Returns FALSE on error. + * the extra space. Returns FALSE if system is out of memory. * ***/ @@ -1267,7 +1275,7 @@ SilcBool silc_buffer_enlarge(SilcBuffer sb, SilcUInt32 size) * is at least the size of `size'. If there is more space than `size' * in the data area this does not do anything. If there is enough * space in the tail area this merely moves the tail area to reveal - * the extra space. Returns FALSE on error. + * the extra space. Returns FALSE if system is out of memory. * * This routine use SilcStack are memory source. If `stack' is NULL * reverts back to normal allocating routine. diff --git a/lib/silcutil/silcbuffmt.h b/lib/silcutil/silcbuffmt.h index fc213001..d1745d1a 100644 --- a/lib/silcutil/silcbuffmt.h +++ b/lib/silcutil/silcbuffmt.h @@ -120,10 +120,10 @@ typedef int (*SilcBufferUnformatFunc)(SilcStack stack, SilcBuffer buffer, * * DESCRIPTION * - * Formats a buffer from a variable argument list. Returns -1 on error - * and the length of the formatted buffer otherwise. The buffer is - * enlarged automatically during formatting, if it doesn't already have - * enough space. + * Formats a buffer from a variable argument list. Returns -1 if the + * system is out of memory and the length of the formatted buffer otherwise. + * The buffer is enlarged automatically during formatting, if it doesn't + * already have enough space. * * EXAMPLE * @@ -181,7 +181,8 @@ int silc_buffer_format(SilcBuffer dst, ...); * DESCRIPTION * * Same as silc_buffer_format but uses `stack' to allocate the memory. - * if `stack' is NULL reverts back to silc_buffer_format call. + * if `stack' is NULL reverts back to silc_buffer_format call. Returns + * -1 if system is out of memory. * * Note that this call consumes the `stack'. The caller should push the * stack before calling the function and pop it later. @@ -198,7 +199,8 @@ int silc_buffer_sformat(SilcStack stack, SilcBuffer dst, ...); * DESCRIPTION * * Formats a buffer from a variable argument list indicated by the `ap'. - * Returns -1 on error and the length of the formatted buffer otherwise. + * Returns -1 if system is out of memory and the length of the formatted + * buffer otherwise. * ***/ int silc_buffer_format_vp(SilcBuffer dst, va_list ap); @@ -212,7 +214,8 @@ int silc_buffer_format_vp(SilcBuffer dst, va_list ap); * DESCRIPTION * * Same as silc_buffer_format_vp but uses `stack' to allocate the memory. - * if `stack' is NULL reverts back to silc_buffer_format_vp call. + * if `stack' is NULL reverts back to silc_buffer_format_vp call. Returns + * -1 if system is out of memory. * * Note that this call consumes the `stack'. The caller should push the * stack before calling the function and pop it later. @@ -306,7 +309,7 @@ int silc_buffer_sunformat_vp(SilcStack stack, SilcBuffer src, va_list ap); * be end with SILC_STRFMT_END argument. This allows that a string in * the list can be NULL, in which case it is skipped. This automatically * allocates the space for the buffer data but `dst' must be already - * allocated by the caller. + * allocated by the caller. Returns -1 if system is out of memory. * * EXAMPLE * @@ -331,7 +334,8 @@ int silc_buffer_strformat(SilcBuffer dst, ...); * the list can be NULL, in which case it is skipped. This automatically * allocates the space for the buffer data but `dst' must be already * allocated by the caller. This function is equivalent to - * silc_buffer_strformat but allocates memory from `stack'. + * silc_buffer_strformat but allocates memory from `stack'. Returns -1 + * if system is out of memory. * * Note that this call consumes the `stack'. The caller should push the * stack before calling the function and pop it later. diff --git a/lib/silcutil/silccond.h b/lib/silcutil/silccond.h index 08110d81..59918a48 100644 --- a/lib/silcutil/silccond.h +++ b/lib/silcutil/silccond.h @@ -75,7 +75,8 @@ typedef struct SilcCondStruct *SilcCond; * Allocates SILC Condition variable context. The condition must * be allocated before it can be used. It is freed by the * silc_cond_free function. This returns TRUE and allocated - * condition in to the `cond' pointer and FALSE on error. + * condition in to the `cond' pointer and FALSE if system is out of + * memory. * ***/ SilcBool silc_cond_alloc(SilcCond *cond); diff --git a/lib/silcutil/silcdlist.h b/lib/silcutil/silcdlist.h index 9c951e49..2a5030a3 100644 --- a/lib/silcutil/silcdlist.h +++ b/lib/silcutil/silcdlist.h @@ -90,7 +90,8 @@ typedef struct SilcDListEntryStruct { * * DESCRIPTION * - * Initializes SilcDList. Returns the SilcDList context or NULL on error. + * Initializes SilcDList. Returns the SilcDList context or NULL if system + * is out of memory. * ***/ diff --git a/lib/silcutil/silcenv.h b/lib/silcutil/silcenv.h index 925caa3d..f8474c6c 100644 --- a/lib/silcutil/silcenv.h +++ b/lib/silcutil/silcenv.h @@ -41,7 +41,7 @@ * Sets the environment variable named `variable' with value `value' * to the environment. If the `variable' already exists in the * environment its value is changed to `value'. Returns FALSE if the - * value could not be set or if environment variable are not supported. + * value could not be set or if environment variables are not supported. * ***/ SilcBool silc_setenv(const char *variable, const char *value); diff --git a/lib/silcutil/silcfdstream.h b/lib/silcutil/silcfdstream.h index 64946c3f..604c0b90 100644 --- a/lib/silcutil/silcfdstream.h +++ b/lib/silcutil/silcfdstream.h @@ -44,7 +44,7 @@ * * Creates file descriptor stream for the open file descriptor indicated * by `fd'. The stream is closed with the silc_stream_close and destroyed - * with the silc_stream_destroy. + * with the silc_stream_destroy. Returns NULL if system is out of memory. * * If the silc_stream_set_notifier is called the stream is set to * non-blocking mode. @@ -67,7 +67,8 @@ SilcStream silc_fd_stream_create(int fd, SilcStack stack); * Creates file descriptor stream for the open file descriptors indicated * by `read_fd' and `write_fd'. The `read_fd' must be opened for reading * and `write_fd' opened for writing. The stream is closed with the - * silc_stream_close and destroyed with the silc_stream_destroy. + * silc_stream_close and destroyed with the silc_stream_destroy. Returns + * NULL if system is out of memory. * * If the silc_stream_set_notifier is called the stream is set to * non-blocking mode. @@ -90,7 +91,7 @@ SilcStream silc_fd_stream_create2(int read_fd, int write_fd, SilcStack stack); * Same as silc_fd_stream_create but creates the stream by opening the * file indicated by `filename'. If the `reading' is TRUE the file is * opened for reading. If the `writing' is TRUE the file is opened - * for writing. + * for writing. Returns NULL if system is out of memory. * * If the silc_stream_set_notifier is called the stream is set to * non-blocking mode. @@ -113,7 +114,8 @@ SilcStream silc_fd_stream_file(const char *filename, SilcBool reading, * DESCRIPTION * * Same as silc_fd_stream_file but creates the stream by opening `read_file' - * for reading and `write_file' for writing. + * for reading and `write_file' for writing. Returns NULL if system is + * out of memory. * * If the silc_stream_set_notifier is called the stream is set to * non-blocking mode. @@ -136,7 +138,7 @@ SilcStream silc_fd_stream_file2(const char *read_file, const char *write_file, * * Returns the file descriptors associated with the stream. The 'write_fd' * is available only if the stream was created with silc_fd_stream_create2 - * function. + * function. Returns FALSE if the information is not available. * ***/ SilcBool silc_fd_stream_get_info(SilcStream stream, diff --git a/lib/silcutil/silcfsm.h b/lib/silcutil/silcfsm.h index c80a19b7..701182e3 100644 --- a/lib/silcutil/silcfsm.h +++ b/lib/silcutil/silcfsm.h @@ -403,6 +403,7 @@ do { \ * caller must free the returned context with silc_fsm_free. The * `fsm_context' is delivered to every FSM state function. The `schedule' * is the caller's scheduler and the FSM will be run in the scheduler. + * Returns NULL if system is out of memory. * * EXAMPLE * @@ -481,7 +482,7 @@ SilcBool silc_fsm_init(SilcFSM fsm, * thread context with silc_fsm_free. If the 'real_thread' is TRUE * then the thread will actually be executed in real thread, if platform * supports them. The `thread_context' is delivered to every state - * function in the thread. + * function in the thread. Returns NULL if the system is out of memory. * * NOTES * @@ -905,7 +906,8 @@ typedef struct SilcFSMEventObject SilcFSMEventStruct; * some event happens, some thread moves to a specific state or similar. * The FSM Events may also be used in FSM threads that are executed in * real system threads. It is safe to wait and signal the event from - * threads. The `fsm' must be the machine, not a thread. + * threads. The `fsm' must be the machine, not a thread. Returns NULL + * if system is out of memory or `fsm' is not FSM machine. * * Use the macros SILC_FSM_EVENT_WAIT and SILC_FSM_EVENT_TIMEDWAIT to wait * for the event. Use the SILC_FSM_EVENT_SIGNAL macro to signal all the diff --git a/lib/silcutil/silchashtable.h b/lib/silcutil/silchashtable.h index 6cecb274..f7d7f21a 100644 --- a/lib/silcutil/silchashtable.h +++ b/lib/silcutil/silchashtable.h @@ -192,7 +192,7 @@ typedef void (*SilcHashForeach)(void *key, void *context, void *user_context); * it should be a prime. The `hash', `compare' and `destructor' are * the hash function, the key comparison function and key and context * destructor function, respectively. The `hash' is mandatory, the others - * are optional. + * are optional. Returns NULL if system is out of memory. * ***/ SilcHashTable silc_hash_table_alloc(SilcStack stack, diff --git a/lib/silcutil/silcmime.h b/lib/silcutil/silcmime.h index 82aa8eea..664b526a 100644 --- a/lib/silcutil/silcmime.h +++ b/lib/silcutil/silcmime.h @@ -71,7 +71,8 @@ typedef struct SilcMimeAssemblerStruct *SilcMimeAssembler; * * DESCRIPTION * - * Allocates SILC Mime message context. + * Allocates SILC Mime message context. Returns NULL if system is out of + * memory. * ***/ SilcMime silc_mime_alloc(void); @@ -97,7 +98,8 @@ void silc_mime_free(SilcMime mime); * * DESCRIPTION * - * Allocates MIME fragment assembler. + * Allocates MIME fragment assembler. Returns NULL if system is out of + * memory. * ***/ SilcMimeAssembler silc_mime_assembler_alloc(void); -- 2.24.0