From patchwork Mon Jan 6 16:26:10 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Arjun Shankar X-Patchwork-Id: 104188 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 2E1753858C5F for ; Mon, 6 Jan 2025 16:35:43 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 2E1753858C5F Authentication-Results: sourceware.org; dkim=pass (1024-bit key, unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=BfLMAxeM X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTP id 81EE83858C66 for ; Mon, 6 Jan 2025 16:33:17 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 81EE83858C66 Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 81EE83858C66 Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1736181197; cv=none; b=VazKZsfmo2dcIP6UIspGa1xDoIBblV5dYwoGZjPw6JdzW97vf7PmkjFIjtaww2rZM9+mvUEGsnO9RkXyawsMyM8fJoVfUwM/bS/jR6JcsVwzu/oif7gNfi8rHNFPR6Xl7EjGALzyTVRsYlD8xTdub2BWqugZeh1NaKsoHhL2WjA= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1736181197; c=relaxed/simple; bh=TXN3nqqKuGmKVfcvHOu2zhS+aMqBKwF+XK0tkxMJ3tM=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=sgaqtmwNfMi1j21Ut5xVfuHCkxC994IL4AyBe27PqGKuuyIoeAnELyYyV84mvf+CX7xTh+DhXFVHtm3dAAFXSvoUCdt7LJUEIOzvaycrzeHk/bV1ZYAADU4S2v10ktGR5R41ebk0siZa/BcU4+q+jyaFIE1eAM92/XSklUdMPl4= ARC-Authentication-Results: i=1; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 81EE83858C66 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1736181197; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=nj05/m24/4BxJWa6etxk/u4r0K2E2F4f8k5SgnFKd7M=; b=BfLMAxeMaBNS9qjIDdW31X8AgdJx+0OeC+zxl4uvwYKOTjbqO30cnhfAD9vOhittxKSSbe xL3i0nMKfNQvNM+4LUoc1stKkApWQrRquPFFU63cmhyGGbSdgrzHSXR6WQkd/O9RFnH0jH u9F3ZtWmeo3fLFBl4dBpFGa6Ie0iPRU= Received: from mail-qt1-f200.google.com (mail-qt1-f200.google.com [209.85.160.200]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-483-4uWy1gNXOgmj30_I9fONrg-1; Mon, 06 Jan 2025 11:33:16 -0500 X-MC-Unique: 4uWy1gNXOgmj30_I9fONrg-1 X-Mimecast-MFC-AGG-ID: 4uWy1gNXOgmj30_I9fONrg Received: by mail-qt1-f200.google.com with SMTP id d75a77b69052e-467be89d064so189753851cf.3 for ; Mon, 06 Jan 2025 08:33:16 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1736181195; x=1736785995; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=nj05/m24/4BxJWa6etxk/u4r0K2E2F4f8k5SgnFKd7M=; b=AY8CV2nzyMZyNQudu5TPjYmlCkNXCg3MqTNQC7rhUQJPC+XwZKbMhR89OCyrRzT6IT 6w7EICW3KhNzQ+GffT/TUY3jtBkV18hmwYW9qRxqu9cRyFDwF86gGtCdPBtextQLFsr9 XVv7n8DFdZn/UIEoBWSeckqcSTwUgOYAlU2U2WkahXIPWfWZ3Uhlhs13IzAzEoZVSeVf xFrPlA+4jN6qmTFH2RpFUmiUdDddjo7Iy3xwxZH/Gue9VZTVaUXwyTBc6WYJqW84aM+j k9lfb3oVaNalU9KizOtn1dtdLLbxnvtjRagJQRVcYoI/XQxcmUphIpCslrfvYPglOPfH djRA== X-Gm-Message-State: AOJu0YwOSubys8ZLEwlV7X/q5AG+sxGDs4+aa9w/Xw52+kdp1hnDn48l EvVZX0LrBGFuhGzmShtYPliZzvunm2Kp/CkkRuHQDpc1ilpWGk8Htf6gG4qveobCgOOsNIZJ8RX cyIEiSeszOFoiV9l0BUyNNQSnDsQRKYkk3wrs9YL/CSEHxWPMYQHgYoi0V26I9VEeUPFMV8bUad fTPLPdq9rOcP9MNB06kVNGxANZnD/WwwlY+Cnb9g== X-Gm-Gg: ASbGncve8XVsqddoVqBgVZ+4d2tlUOqdD2kvkO5sBZ1KhgmgnUcgoqOlmhmqvGx56Ku kbSUaQ2il6mfXjGySDt/NsTA/mc03X2EU7/2ESgrSYk54eP94Rg6czWKAYVffjTN1N2LZ26igxd Zv4hTdBFEaw2r1YpTZ/fLqMETINuUGahw+DfCON5mM/3xeBvoM+Jbt01tpnDUtxUlHv+XvNh0tM geFEDH4aP8xw4AzSsPdU/Pt/5JTPSLcQ8rI5KXsnGGzwvhKS4Q7u0xUPGAMQIAp2M5U9GTJnbHv TiSEWBoYJQb6FWadM62lz/Br X-Received: by 2002:a05:622a:650:b0:467:7eb6:a007 with SMTP id d75a77b69052e-46a4a98a27bmr863243611cf.37.1736181195259; Mon, 06 Jan 2025 08:33:15 -0800 (PST) X-Google-Smtp-Source: AGHT+IGYUmYkQsOcHrmgsQ2+mgipWNob19X/QtCqjDpfH6OefXeBBEhKmLG1uJs7WGppIa3VpOrElQ== X-Received: by 2002:a05:622a:650:b0:467:7eb6:a007 with SMTP id d75a77b69052e-46a4a98a27bmr863243281cf.37.1736181194891; Mon, 06 Jan 2025 08:33:14 -0800 (PST) Received: from x1carbon9g.redhat.com (ip-94-112-226-240.bb.vodafone.cz. [94.112.226.240]) by smtp.gmail.com with ESMTPSA id d75a77b69052e-46a3e67e361sm176664841cf.31.2025.01.06.08.33.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 06 Jan 2025 08:33:14 -0800 (PST) From: Arjun Shankar To: libc-alpha@sourceware.org Cc: Arjun Shankar Subject: [PATCH v2 5/5] manual: Document futimens and utimensat Date: Mon, 6 Jan 2025 17:26:10 +0100 Message-ID: <20250106163257.705106-6-arjun@redhat.com> X-Mailer: git-send-email 2.47.1 In-Reply-To: <20250106163257.705106-1-arjun@redhat.com> References: <20250106163257.705106-1-arjun@redhat.com> MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: PkSLAyeatR5PviV3JqNCEWXFpv92B9IGH42hNMFfU18_1736181196 X-Mimecast-Originator: redhat.com content-type: text/plain; charset="US-ASCII"; x-default=true X-Spam-Status: No, score=-11.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_BARRACUDACENTRAL, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_NONE, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces~patchwork=sourceware.org@sourceware.org --- manual/filesys.texi | 69 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-) diff --git a/manual/filesys.texi b/manual/filesys.texi index ba2f13ef96..a5a5e1a1b4 100644 --- a/manual/filesys.texi +++ b/manual/filesys.texi @@ -3273,6 +3273,74 @@ The file lives on a read-only file system. @end table @end deftypefun +@deftypefun int futimens (int @var{filedes}, const struct timespec @var{tsp}@t{[2]}) +@standards{POSIX.1-2008, sys/stat.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is like @code{futimes}, except that it sets the file access +and modification timestamps with nanosecond precision. The argument +@code{tsp} is used similarly to @code{futimes}' @code{tvp}, but has a +@code{struct timespec} type that can express calendar time with nanosecond +precision; see @ref{Time Types}. + +Compared to @code{futimes}, the following additional error conditions can +occur: + +@table @code +@item EFAULT +The @var{tsp} argument points to an invalid address. + +@item EINVAL +At least of the fields in the @code{tsp} array passed has an invalid value. + +@end table +@end deftypefun + +@deftypefun int utimensat (int @var{filedes}, const char *@var{filename}, const struct timespec @var{tsp}@t{[2]}, int @var{flags}) +@standards{POSIX.1-2008, sys/stat.h} +@comment Unaudited and therefore marked AC-Unsafe and AS-Unsafe by default +@safety{@mtsafe{}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}} +This function is a descriptor-relative version of the @code{futimens} +function above. @xref{Descriptor-Relative Access}. The @var{flags} +argument can contain a combination of the flags @code{AT_EMPTY_PATH}, +and @code{AT_SYMLINK_NOFOLLOW}. + +Compared to @code{futimens}, the following additional error conditions can +occur: + +@table @code +@item EFAULT +The @var{filedes} argument is @code{AT_FDCWD} and @var{filename} is NULL or +points to an invalid address. + +@item EINVAL +The @var{flags} argument is not valid for this function. + +@item EINVAL +The @var{filename} argument is NULL, @var{filedes} is not @code{AT_FDCWD}, +and @var{flags} contains @code{AT_SYMLINK_NOFOLLOW}. + +@item ELOOP +There are too many levels of indirection. This can be the result of +circular symbolic links to directories. + +@item ENAMETOOLONG +The resulting path is too long. This error only occurs on systems which +have a limit on the file name length. + +@item ENOENT +The @var{filename} argument is an empty string or does not refer to an +existing file. + +@item ENOTDIR +The file descriptor @var{filedes} is not associated with a directory. + +@item ESRCH +Search permission was denied for one of the prefix components of the the +@var{filename} argument. +@end table +@end deftypefun + @node File Size @subsection File Size @@ -3889,5 +3957,4 @@ The @code{mkdtemp} function comes from OpenBSD. @c renameat2 @c scandirat @c symlinkat -@c utimensat @c mknodat