From nobody Thu Apr 2 18:29:59 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=pass(p=reject dis=none) header.from=lists.libvirt.org ARC-Seal: i=1; a=rsa-sha256; t=1774605688; cv=none; d=zohomail.com; s=zohoarc; b=IJYnoZsbNE6wqQUfUYR9Jt5Hs0JHzh4+GHLszsR6Ku2WPmyVcOoJk1Z2FS0ct6J7ahI47b/An/Y/OLDYeS6nHZNwSTyQWEQqrns1u6RXi0sehc1iDYiI4QIVq3twz9H+A4Evi8Hq4LTHuNObgWuxeX99fUgzpnnmlbRRlXjVJvI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1774605688; h=Content-Type:Content-Transfer-Encoding:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Owner:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:Reply-To:References:Subject:Subject:To:To:Message-Id:Cc; bh=lR7UVWoVUGt/24AccI7U0A53fYQvECvYEYk/Z8W6kv4=; b=hC42ioM3JX2cCK8YGChJTtr/O55nHLnkNs072tcd44eJLs8CF34HOnXNhml1o9d/VwXC6oQB8ohitk6No7cSk6/wmtAERTLCNkrpZJsggRzPVnej+kHedX47d1XeziFQxszXVGZqMS7ykCFaDbdsYDFD9qnlPXadpEU8PM3Yncw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=pass header.from= (p=reject dis=none) Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 1774605688215208.62016024685363; Fri, 27 Mar 2026 03:01:28 -0700 (PDT) Received: by lists.libvirt.org (Postfix, from userid 993) id 4367141832; Fri, 27 Mar 2026 06:01:27 -0400 (EDT) Received: from [172.19.199.12] (lists.libvirt.org [8.43.85.245]) by lists.libvirt.org (Postfix) with ESMTP id 5F90C41B03; Fri, 27 Mar 2026 05:57:46 -0400 (EDT) Received: by lists.libvirt.org (Postfix, from userid 993) id 9BE3A3F86B; Fri, 27 Mar 2026 05:57:40 -0400 (EDT) Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (3072 bits) server-digest SHA256) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id 43D4E3F802 for ; Fri, 27 Mar 2026 05:55:00 -0400 (EDT) Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-580-Ml81_2o0OaGtD8D94RpbPg-1; Fri, 27 Mar 2026 05:54:57 -0400 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E1C6219560A6 for ; Fri, 27 Mar 2026 09:54:56 +0000 (UTC) Received: from speedmetal.openshiftapps.com (unknown [10.45.242.5]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 38F2230001A1 for ; Fri, 27 Mar 2026 09:54:56 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 4.0.1 (2024-03-26) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-4.7 required=5.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,HELO_MISC_IP,MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED,SPF_PASS autolearn=unavailable autolearn_force=no version=4.0.1 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1774605299; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=lR7UVWoVUGt/24AccI7U0A53fYQvECvYEYk/Z8W6kv4=; b=LZA98LVpc/f3tm2z6kzatN9FaMkBuih+P57TOBu55KpSHCJh/V7hVNKVyApS2RDI7fF8+1 btZqM1Qj2eBcEpVUtPHly0oklBj+EnHaZr4hZtigOhLx0JWL6joUorTa8IlxLx20dUc9wV 5tNZR0qcyl7T5NJAJtTI3zGFPUMvsM0= X-MC-Unique: Ml81_2o0OaGtD8D94RpbPg-1 X-Mimecast-MFC-AGG-ID: Ml81_2o0OaGtD8D94RpbPg_1774605297 To: devel@lists.libvirt.org Subject: [PATCH 5/6] util: virfile: Document the various functions for reading from file/fd Date: Fri, 27 Mar 2026 10:54:43 +0100 Message-ID: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: xyR4f_td0Oug4MY8I4Uspe8Q9HNQqFIxTQrT5e1u9U8_1774605297 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Message-ID-Hash: B6VGAYHO3DPWER24CT5MREPFU4GY6V42 X-Message-ID-Hash: B6VGAYHO3DPWER24CT5MREPFU4GY6V42 X-MailFrom: pkrempa@redhat.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; header-match-devel.lists.libvirt.org-0; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.10 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: From: Peter Krempa via Devel Reply-To: Peter Krempa X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1774605689067158500 Content-Type: text/plain; charset="utf-8" From: Peter Krempa Document both the behaviour if requested length isn't enough to read the file as well as the semantics of NUL-termination of the buffer. Signed-off-by: Peter Krempa --- src/util/virfile.c | 140 ++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 126 insertions(+), 14 deletions(-) diff --git a/src/util/virfile.c b/src/util/virfile.c index fbcaf15429..bc3faedd4e 100644 --- a/src/util/virfile.c +++ b/src/util/virfile.c @@ -1534,10 +1534,27 @@ saferead_lim(int fd, size_t max_len, size_t *length) } -/* A wrapper around saferead_lim that merely stops reading at the - * specified maximum size. */ +/** + * virFileReadHeaderQuiet: + * @fd: file descriptor to read + * @maxlen: maximum amount of bytes to read + * @buf: filled with allocated buffer containing read data + * + * Reads up to @maxlen bytes from @fd and fills @buf with pointer to the + * read contents. + * + * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte o= ne + * byte beyond the read contents of the file. The NUL byte is not included= in + * the returned amount of bytes read. Caller is responsible for freeing the + * buffer. + * + * Returns number of bytes actually read from the fd on success, -1 on err= or + * and doesn't raise a libvirt error. + */ int -virFileReadHeaderFD(int fd, int maxlen, char **buf) +virFileReadHeaderFD(int fd, + int maxlen, + char **buf) { size_t len; char *s; @@ -1554,6 +1571,26 @@ virFileReadHeaderFD(int fd, int maxlen, char **buf) } +/** + * virFileReadHeaderQuiet: + * @path: file to read + * @maxlen: maximum length of file to read + * @buf: filled with allocated buffer containing read data + * + * Reads up to @maxlen bytes from file @path and fills @buf with pointer t= o the + * read contents. + * + * If file @path is longer than @maxlen the buffer contains only first @ma= xlen + * bytes read from the file. + * + * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte o= ne + * byte beyond the read contents of the file. The NUL byte is not included= in + * the returned amount of bytes read. Caller is responsible for freeing the + * buffer. + * + * Returns number of bytes actually read from file on success, -1 on error + * and doesn't raise a libvirt error. + */ int virFileReadHeaderQuiet(const char *path, int maxlen, @@ -1573,10 +1610,29 @@ virFileReadHeaderQuiet(const char *path, } -/* A wrapper around saferead_lim that maps a failure due to - exceeding the maximum size limitation to EOVERFLOW. */ +/** + * virFileReadLimFD: + * @fd: file descriptor to read + * @maxlen: maximum amount of bytes to read + * @buf: filled with allocated buffer containing read data + * + * Reads the whole contents from @fd and fills @buf with pointer to the re= ad + * contents. + * + * If @fd allowed reading more than @maxlen bytes an error is returned. + * + * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte o= ne + * byte beyond the read contents of the file. The NUL byte is not included= in + * the returned amount of bytes read. Caller is responsible for freeing the + * buffer. + * + * Returns number of bytes actually read from @fd on success, -1 on error = and + * doesn't raise a libvirt error. + */ int -virFileReadLimFD(int fd, int maxlen, char **buf) +virFileReadLimFD(int fd, + int maxlen, + char **buf) { size_t len; char *s; @@ -1599,8 +1655,29 @@ virFileReadLimFD(int fd, int maxlen, char **buf) return len; } + +/** + * virFileReadAll: + * @path: file to read + * @maxlen: maximum length of file to read + * @buf: filled with allocated buffer containing read data + * + * Reads the whole file @path and fills @buf with pointer to the read cont= ents. + * + * If file @path is longer than @maxlen error is returned. + * + * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte o= ne + * byte beyond the read contents of the file. The NUL byte is not included= in + * the returned amount of bytes read. Caller is responsible for freeing the + * buffer. + * + * Returns number of bytes actually read from file on success, -1 on error= and + * raises a libvirt error. + */ int -virFileReadAll(const char *path, int maxlen, char **buf) +virFileReadAll(const char *path, + int maxlen, + char **buf) { int fd; int len; @@ -1621,8 +1698,29 @@ virFileReadAll(const char *path, int maxlen, char **= buf) return len; } + +/** + * virFileReadAllQuiet: + * @path: file to read + * @maxlen: maximum length of file to read + * @buf: filled with allocated buffer containing read data + * + * Reads the whole file @path and fills @buf with pointer to the read cont= ents. + * + * If file @path is longer than @maxlen error is returned. + * + * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte o= ne + * byte beyond the read contents of the file. The NUL byte is not included= in + * the returned amount of bytes read. Caller is responsible for freeing the + * buffer. + * + * Returns number of bytes actually read from file on success, -errno on e= rror + * and doesn't raise a libvirt error. + */ int -virFileReadAllQuiet(const char *path, int maxlen, char **buf) +virFileReadAllQuiet(const char *path, + int maxlen, + char **buf) { int fd; int len; @@ -1639,13 +1737,26 @@ virFileReadAllQuiet(const char *path, int maxlen, c= har **buf) return len; } -/* Read @file into preallocated buffer @buf of size @len. - * Return value is -errno in case of errors and size - * of data read (no trailing zero) in case of success. - * If there is more data then @len - 1 then data will be - * truncated. */ + +/** + * virFileReadBufQuiet: + * @file: file to read + * @buf: buffer to read files into + * @len: size of @buf + * + * Reads up to @len - 1 bytes of @file into @buf. + * + * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte o= ne + * byte beyond the read contents of the file. The NUL byte is not included= in + * the returned amount of bytes read. + * + * Returns number of bytes actually read from file on success, -errno on e= rror + * and doesn't raise a libvirt error. + */ int -virFileReadBufQuiet(const char *file, char *buf, int len) +virFileReadBufQuiet(const char *file, + char *buf, + int len) { int fd; ssize_t sz; @@ -1663,6 +1774,7 @@ virFileReadBufQuiet(const char *file, char *buf, int = len) return sz; } + /* Truncate @path and write @str to it. If @mode is 0, ensure that @path exists; otherwise, use @mode if @path must be created. Return 0 for success, nonzero for failure. --=20 2.53.0