From 6703c9a063a61320294aa2cc519a911a4e76d49b Mon Sep 17 00:00:00 2001 From: Andre Date: Fri, 5 Jan 2007 17:59:22 +0100 Subject: [PATCH] net.c: More documentation improvements Add documentation of struct crypt_data and friends. Always document the return value if non-void. --- net.c | 32 +++++++++++++++++++++++++------- 1 file changed, 25 insertions(+), 7 deletions(-) diff --git a/net.c b/net.c index 70aacd8c..6a8eea3b 100644 --- a/net.c +++ b/net.c @@ -1,5 +1,5 @@ /* - * Copyright (C) 2005-2006 Andre Noll + * Copyright (C) 2005-2007 Andre Noll * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by @@ -24,15 +24,19 @@ #include "error.h" -/** \cond holds information about one encrypted connection */ +/** holds information about one encrypted connection */ struct crypt_data { + /** function used to decrypt received data */ crypt_function *recv; + /** function used to encrypt data to be sent */ crypt_function *send; + /** context-dependent data, passed to \a recv() and \a send() */ void *private_data; }; -static unsigned cda_size = 0; +/** array holding per fd crypt data per */ static struct crypt_data *crypt_data_array; -/** \endcond */ +/** current size of the crypt data array */ +static unsigned cda_size = 0; /** @@ -212,7 +216,7 @@ __printf_2_3 int send_va_buffer(int fd, const char *fmt, ...) * Receive at most \a size bytes from filedescriptor fd. If encryption is * available, decrypt the received buffer. * - * \return the number of bytes received on success. On receive errors, -E_RECV + * \return The number of bytes received on success. On receive errors, -E_RECV * is returned. On crypt errors, the corresponding crypt error number is * returned. * @@ -249,7 +253,10 @@ __must_check int recv_bin_buffer(int fd, char *buf, ssize_t size) * Read and decrypt at most \a size - 1 bytes from file descriptor \a fd and * write a NULL byte at the end of the received data. * -*/ + * \return: The return value of the underlying call to \a recv_bin_buffer(). + * + * \sa recv_bin_buffer() + */ int recv_buffer(int fd, char *buf, ssize_t size) { int n; @@ -307,6 +314,7 @@ int get_socket(void) * \param their_addr the address to connect * * \return \p -E_CONNECT on errors, 1 on success + * * \sa connect(2) */ int para_connect(int fd, struct sockaddr_in *their_addr) @@ -326,13 +334,17 @@ int para_connect(int fd, struct sockaddr_in *their_addr) * \param addr structure which is filled in with the address of the peer socket * \param size should contain the size of the structure pointed to by \a addr * + * Accept incoming connections on \a addr. Retry if interrupted. + * + * \return The new file descriptor on success, \a -E_ACCEPT on errors. + * * \sa accept(2). */ int para_accept(int fd, void *addr, socklen_t size) { int new_fd; - do + do new_fd = accept(fd, (struct sockaddr *) addr, &size); while (new_fd < 0 && errno == EINTR); return new_fd < 0? -E_ACCEPT : new_fd; @@ -378,6 +390,9 @@ int init_unix_addr(struct sockaddr_un *u, const char *name) * * This functions creates a local socket for sequenced, reliable, * two-way, connection-based byte streams. + * + * \return The file descriptor, on success, negative on errors. + * * \sa socket(2) * \sa bind(2) * \sa chmod(2) @@ -418,6 +433,7 @@ int recv_cred_buffer(int fd, char *buf, size_t size) * * \return On success, this call returns the number of characters sent. On * error, \p -E_SENDMSG ist returned. + * * \sa okir's Black Hats Manual * \sa sendmsg(2) */ @@ -521,6 +537,7 @@ int recv_cred_buffer(int fd, char *buf, size_t size) /** * create a socket, bind it and listen + * * \param port the tcp port to listen on * * \return The file descriptor of the created socket, negative @@ -572,6 +589,7 @@ err: * to receive at most \a bufsize bytes from file descriptor \a fd. * If at least \p strlen(\a pattern) bytes were received, the beginning of * the received buffer is compared with \a pattern, ignoring case. + * * \sa recv_buffer() * \sa strncasecmp(3) */ -- 2.39.5