From nobody Mon Apr 11 02:07:41 2022 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 91ACD1A9257F; Mon, 11 Apr 2022 02:07:43 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4KcC1B2vrPz3LBQ; Mon, 11 Apr 2022 02:07:42 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1649642862; 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; bh=8ADvELKNUMz5eOdI7NF71uKUx9aiwTG9QG96aHsxCbw=; b=WTWwL94zCSop5kl5r/2v4aeBOjGqIbqX+baGyqByKtzz3ocACEZ01mjfgg3+Ac1AzqZn6j SZ6gzmja1ZgbwssakNKRzYIaiolDqLUilaTaXfdx5+PS5O2lT2FmtsVRoaMQ5h878vXKdB jeMWo8TJc/L79NWyZNDJGrWvB2TvIi3meCYcnsy4q8/18CbjLIhI4jbT8Eek5OwipPO0N5 fvOZvPjmXL95DVVSJUU6oPohiU6q4XQHfQU6MMAlrgSHyBlEPuQ02Mwubio+Y/2zbXXajV andQdihjrUKE2WI29794AkeM42yLtiCy2i+cXB4PNbWvPfPGVdAktrmB5B3e6A== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 04C691A3B4; Mon, 11 Apr 2022 02:07:42 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.16.1/8.16.1) with ESMTP id 23B27f9n086290; Mon, 11 Apr 2022 02:07:41 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.16.1/8.16.1/Submit) id 23B27fBK086289; Mon, 11 Apr 2022 02:07:41 GMT (envelope-from git) Date: Mon, 11 Apr 2022 02:07:41 GMT Message-Id: <202204110207.23B27fBK086289@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Enji Cooper Subject: git: 57d53eb6832f - stable/12 - extattr_get_file(2): clarify RETURN VALUES List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: Sender: owner-dev-commits-src-main@freebsd.org X-BeenThere: dev-commits-src-main@freebsd.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: ngie X-Git-Repository: src X-Git-Refname: refs/heads/stable/12 X-Git-Reftype: branch X-Git-Commit: 57d53eb6832f78cdf42e6ded97f7b5e64a829eb7 Auto-Submitted: auto-generated ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1649642862; 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; bh=8ADvELKNUMz5eOdI7NF71uKUx9aiwTG9QG96aHsxCbw=; b=slrZnY1jnmEk4RSJtt3MJTBnoxYWK/jBs0NPv/Lxtjgil6hHyGVX0kSt+x+bKyANqGZjTZ jGkoxpcMQzAqC2V6mXg9ngqerj50SyQA0gEGyGkJD5YblEKkZiIVlSlQQyGUZN7RoDqUBk x+QCczXo83+6dl3ikG5nGCqUM5URTuSQS5JUgugkfqqq2YxwHYmMWKuNJUr3Aj4aZiMpvz ZSs4TjVx75z8AF9PQsuW+CfgE7UP8q/4crvCZxqqNBl+RGKTpvrHTDeV0iLTuxyE+Tzd2I khECZgj16qUwaLraAPqKNxE4Xh8IVEtLzIxUaD4pmZHE52WMVYuwweAAvhf4cw== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1649642862; a=rsa-sha256; cv=none; b=jGBQVwshNGuQ9UFyw27S3bqN9Rl3oZSGL9uEvSGSfOBseAX2dIjiqUTEUll7MY6oMSoX00 7716ebWm5m/LzLbMUeH2BR7WWQI+XKD9tQxAiSop1NVreeG4pr/etilabU/N3T377NrZW3 BJUstmYkbgdpqJXsmXqozYNtY9b3s5FwCeHh78myxzS9TUVQHOdXs7AWjoresUHuev9TA9 oIFxA4HGQUQbyr8ieUFSA6CBIekbsry6y4i2LRupQeeIX6jjo4Q+tp2/dSDCQ/A4IJCBWo 8p+A0OstodvJGxtB9vu6UN7Emq3x1GhjZWhIw7hqlMPsK33MDMoKiN90A0LtHg== ARC-Authentication-Results: i=1; mx1.freebsd.org; none X-ThisMailContainsUnwantedMimeParts: N The branch stable/12 has been updated by ngie: URL: https://cgit.FreeBSD.org/src/commit/?id=57d53eb6832f78cdf42e6ded97f7b5e64a829eb7 commit 57d53eb6832f78cdf42e6ded97f7b5e64a829eb7 Author: Enji Cooper AuthorDate: 2020-12-08 04:16:05 +0000 Commit: Enji Cooper CommitDate: 2022-04-11 01:23:36 +0000 extattr_get_file(2): clarify RETURN VALUES While some of the syscalls' behavior were documented and implied in the RETURN VALUES section by earlier, e.g., the DESCRIPTION sections, as having behavior of the other calls (`*_fd` vs `*_file` vs `*_link`), there was a lot of implied return value behavior in the section prior to this change. Explicitly document the syscall behavior per the current implementation in sys/kern/vfs_extattr.c so others can better develop based on its explicit documented behavior instead of having to digest the context of the manpage to understand the appropriate behavior. MFC after: 1 week MFC with: r368431, r368433, r368434 Sponsored by: DellEMC Isilon (cherry picked from commit cf681016d47ed689da60c8cfe1a4fb894e036b4d) --- lib/libc/sys/extattr_get_file.2 | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/lib/libc/sys/extattr_get_file.2 b/lib/libc/sys/extattr_get_file.2 index a9a2defa8448..bc46440d46ab 100644 --- a/lib/libc/sys/extattr_get_file.2 +++ b/lib/libc/sys/extattr_get_file.2 @@ -169,21 +169,32 @@ For more information on named extended attributes, please see .Xr extattr 9 . .Sh RETURN VALUES If successful, the +.Fn extattr_get_fd , .Fn extattr_get_file , +.Fn extattr_get_link , +.Fn extattr_list_fd , +.Fn extattr_list_file , +.Fn extattr_list_link , +.Fn extattr_set_fd , .Fn extattr_set_file , and -.Fn extattr_list_file +.Fn extattr_set_link calls return the number of bytes that were read or written from the .Fa data , -respectively, or if +respectively. +If .Fa data was .Dv NULL , then -.Fn extattr_get_file +.Fn extattr_get_fd , +.Fn extattr_get_file , +.Fn extattr_get_link , +.Fn extattr_list_fd , +.Fn extattr_list_file , and -.Fn extattr_list_file +.Fn extattr_list_link return the number of bytes available to read. If any of the calls are unsuccessful, the value \-1 is returned and the global variable