From patchwork Tue Oct 9 21:37:31 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antonio Quartulli X-Patchwork-Id: 533 Return-Path: Delivered-To: patchwork@openvpn.net Delivered-To: patchwork@openvpn.net Received: from director9.mail.ord1d.rsapps.net ([172.27.255.58]) by backend30.mail.ord1d.rsapps.net with LMTP id 8BqyHwe7vVu5dwAAIUCqbw for ; Wed, 10 Oct 2018 04:40:39 -0400 Received: from proxy6.mail.iad3a.rsapps.net ([172.27.255.58]) by director9.mail.ord1d.rsapps.net with LMTP id kGl1HQe7vVu+cwAAalYnBA ; Wed, 10 Oct 2018 04:40:39 -0400 Received: from smtp53.gate.iad3a ([172.27.255.58]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by proxy6.mail.iad3a.rsapps.net with LMTP id aHo3GAe7vVvNcQAA8udqhg ; Wed, 10 Oct 2018 04:40:39 -0400 X-Spam-Threshold: 95 X-Spam-Score: 0 X-Spam-Flag: NO X-Virus-Scanned: OK X-Orig-To: openvpnslackdevel@openvpn.net X-Originating-Ip: [216.105.38.7] Authentication-Results: smtp53.gate.iad3a.rsapps.net; iprev=pass policy.iprev="216.105.38.7"; spf=pass smtp.mailfrom="openvpn-devel-bounces@lists.sourceforge.net" smtp.helo="lists.sourceforge.net"; dkim=fail (signature verification failed) header.d=sourceforge.net; dkim=fail (signature verification failed) header.d=sf.net; dmarc=none (p=nil; dis=none) header.from=unstable.cc X-Suspicious-Flag: YES X-Classification-ID: 29958a7e-cc68-11e8-8969-5254009c3572-1-1 Received: from [216.105.38.7] ([216.105.38.7:12067] helo=lists.sourceforge.net) by smtp53.gate.iad3a.rsapps.net (envelope-from ) (ecelerity 4.2.38.62370 r(:)) with ESMTPS (cipher=DHE-RSA-AES256-GCM-SHA384) id 9A/EC-18643-60BBDBB5; Wed, 10 Oct 2018 04:40:39 -0400 Received: from [127.0.0.1] (helo=sfs-ml-1.v29.lw.sourceforge.com) by sfs-ml-1.v29.lw.sourceforge.com with esmtp (Exim 4.90_1) (envelope-from ) id 1gAA1k-0002O1-SE; Wed, 10 Oct 2018 08:39:32 +0000 Received: from [172.30.20.202] (helo=mx.sourceforge.net) by sfs-ml-1.v29.lw.sourceforge.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.90_1) (envelope-from ) id 1gAA1j-0002NF-AX for openvpn-devel@lists.sourceforge.net; Wed, 10 Oct 2018 08:39:31 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sourceforge.net; s=x; h=Content-Transfer-Encoding:MIME-Version:Message-Id: Date:Subject:Cc:To:From:Sender:Reply-To:Content-Type:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:In-Reply-To:References:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=bpSv2kKqMw8oaxENdfjyMItss/LjeqgsNt9LSweh0xU=; b=hiVy8yt2Q6MNjeH0Q5zNp7RoOZ UmtARg61o6rxTuzAJ5CoOZ7uZ38vT/Nj125/ZX4oiTk7Y/95aiPOwX9kQB0QiCpy7Ovj9e+DPAQVI gtNja1HMTnpS6LXW4BPJGiMesuADrpBHam3wUJBZSrZa851zxtaiH21cE5vW08bn+bQY=; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sf.net; s=x ; h=Content-Transfer-Encoding:MIME-Version:Message-Id:Date:Subject:Cc:To:From :Sender:Reply-To:Content-Type:Content-ID:Content-Description:Resent-Date: Resent-From:Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:In-Reply-To: References:List-Id:List-Help:List-Unsubscribe:List-Subscribe:List-Post: List-Owner:List-Archive; bh=bpSv2kKqMw8oaxENdfjyMItss/LjeqgsNt9LSweh0xU=; b=P MNeOEmG8AgMH6EwwdCPTKtRZKKCFgoCru0vKhA3FzBdgqT8qTolbOi0FW4jy8zwtK80Ptrt7zrnR0 hGRqwz93r2FUHS24QaA9WGFuubBvz1lFsCqb6fp4Cq2dBqBEUhgUKSrInvUHhX0MqsBKOdHDSt1rS MKgFS6BIR7pql94E=; Received: from s2.neomailbox.net ([5.148.176.60]) by sfi-mx-2.v28.lw.sourceforge.com with esmtps (TLSv1.2:DHE-RSA-AES256-GCM-SHA384:256) (Exim 4.90_1) id 1gAA1f-00GYUu-76 for openvpn-devel@lists.sourceforge.net; Wed, 10 Oct 2018 08:39:31 +0000 From: Antonio Quartulli To: openvpn-devel@lists.sourceforge.net Date: Wed, 10 Oct 2018 16:37:31 +0800 Message-Id: <20181010083731.31132-1-a@unstable.cc> MIME-Version: 1.0 X-Spam-Report: Spam Filtering performed by mx.sourceforge.net. See http://spamassassin.org/tag/ for more details. -0.0 RCVD_IN_DNSWL_NONE RBL: Sender listed at http://www.dnswl.org/, no trust [5.148.176.60 listed in list.dnswl.org] -0.0 SPF_PASS SPF: sender matches SPF record X-Headers-End: 1gAA1f-00GYUu-76 Subject: [Openvpn-devel] [PATCH] buffer_list: add functions documentation X-BeenThere: openvpn-devel@lists.sourceforge.net X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Antonio Quartulli Errors-To: openvpn-devel-bounces@lists.sourceforge.net X-getmail-retrieved-from-mailbox: Inbox bufferlist_* functions have no documentation whatsoever and the name is not always enough to fully understand what the function is doing. For this reason and for the sake of having better documented code, add function doc in buffer.h. Signed-off-by: Antonio Quartulli Acked-by: Steffan Karger --- Some doc might be extended and some might be unecessary. Still I think it is good to start having doc for more helper functions we have around. src/openvpn/buffer.h | 67 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) diff --git a/src/openvpn/buffer.h b/src/openvpn/buffer.h index cb9e9dff..dbc5bfc3 100644 --- a/src/openvpn/buffer.h +++ b/src/openvpn/buffer.h @@ -1091,26 +1091,93 @@ struct buffer_list int max_size; /* maximum size list should grow to */ }; +/** + * Allocate an empty buffer list of capacity \c max_size. + * + * @param max_size the capacity of the list to allocate + * + * @return the new list + */ struct buffer_list *buffer_list_new(const int max_size); +/** + * Frees a buffer list and all the buffers in it. + * + * @param ol the list to free + */ void buffer_list_free(struct buffer_list *ol); +/** + * Checks if the list is valid and non-empty + * + * @param ol the list to check + * + * @return true iff \c ol is not NULL and contains at least one buffer + */ bool buffer_list_defined(const struct buffer_list *ol); +/** + * Empty the list \c ol and frees all the contained buffers + * + * @param ol the list to reset + */ void buffer_list_reset(struct buffer_list *ol); +/** + * Allocates and appends a new buffer containing \c str as data to \c ol + * + * @param ol the list to append the new buffer to + * @param str the string to copy into the new buffer + */ void buffer_list_push(struct buffer_list *ol, const char *str); +/** + * Allocatea and appends a new buffer containing \c data of length \c size. + * + * @param ol the list to append the new buffer to + * @param data the data to copy into the new buffer + * @param size the length of \c data to copy into the buffer + * + * @return the new buffer + */ struct buffer_entry *buffer_list_push_data(struct buffer_list *ol, const void *data, size_t size); +/** + * Retrieve the head buffer + * + * @param ol the list to retrieve the buffer from + * + * @return a pointer to the head buffer or NULL if the list is empty + */ struct buffer *buffer_list_peek(struct buffer_list *ol); void buffer_list_advance(struct buffer_list *ol, int n); void buffer_list_pop(struct buffer_list *ol); +/** + * Aggregates as many buffers as possible from \c bl in a new buffer of maximum + * length \c max_len . + * All the aggregated buffers are removed from the list and replaced by the new + * one, followed by any additional (non-aggregated) data. + * + * @param bl the list of buffer to aggregate + * @param max the maximum length of the aggregated buffer + */ void buffer_list_aggregate(struct buffer_list *bl, const size_t max); +/** + * Aggregates as many buffers as possible from \c bl in a new buffer + * of maximum length \c max_len . \c sep is written after + * each copied buffer (also after the last one). All the aggregated buffers are + * removed from the list and replaced by the new one, followed by any additional + * (non-aggregated) data. + * Nothing happens if \c max_len is not enough to aggregate at least 2 buffers. + * + * @param bl the list of buffer to aggregate + * @param max_len the maximum length of the aggregated buffer + * @param sep the separator to put between buffers during aggregation + */ void buffer_list_aggregate_separator(struct buffer_list *bl, const size_t max_len, const char *sep);