From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-20.4 required=3.0 tests=BAYES_00,DKIMWL_WL_MED, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,FSL_HELO_FAKE, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_IN_DEF_DKIM_WL autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 47BE4C4338F for ; Thu, 5 Aug 2021 06:35:20 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 26EDD60525 for ; Thu, 5 Aug 2021 06:35:20 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S235754AbhHEGfc (ORCPT ); Thu, 5 Aug 2021 02:35:32 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:46054 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S231154AbhHEGfc (ORCPT ); Thu, 5 Aug 2021 02:35:32 -0400 Received: from mail-pl1-x62e.google.com (mail-pl1-x62e.google.com [IPv6:2607:f8b0:4864:20::62e]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id D51B6C0613C1 for ; Wed, 4 Aug 2021 23:35:18 -0700 (PDT) Received: by mail-pl1-x62e.google.com with SMTP id e5so5883202pld.6 for ; Wed, 04 Aug 2021 23:35:18 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20161025; h=date:from:to:cc:subject:message-id:references:mime-version :content-disposition:in-reply-to; bh=yw+dfXvJIDBVeZYoVj8XzX5qi4Azokeflw5Ku86+K6w=; b=GTDi+zK4gVfIGBCxIO46T6VDh1Knx03ODP2kRO1DnNsUOPLAeE6v/vSDGzYkycfWtX VYwqqxBDCuvvHs5SShVCIQudMwYb/AlfeasjvmOR4eHsV8B/424D0xpPGoci681z139U DBFzjU1NV7yibp5JbmkBhVFSxRu1NlQUr6CTbhoyd67k+k32XQGfYA3FVp52kIBL5ndT ejpAtNanR2uAg4G03ajOUw5vh91PGH7GruVkgTUw4iU1bpLjH20TPw6nCIOpAqgmjSKX Ahv0F1ykQck6neW24kGBcGelHF6i/ud4jMld+GrqcWZchonJSz9eU3gAKc3fLfmGMn0u z66g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:date:from:to:cc:subject:message-id:references :mime-version:content-disposition:in-reply-to; bh=yw+dfXvJIDBVeZYoVj8XzX5qi4Azokeflw5Ku86+K6w=; b=qkKbsHQBjUuxaDBUWNKgrlb4ivEzc2nqITOpBT7OgJEbS2FRrVL4EkGDSS5UklvFEG m6phTjZxV12ta8ARYnOt88tRMGcR/5SaXbLuuPBptUNEBKJNphgFEFx53qRSz8n2elXY guaXjjCA1qTrZRmu3nNj4S8gnLMlGX3WPbnFt/3vl4ceCjlE0DQm73qHCS6lA3cGk1Q2 Q7r2SUQjwJ06GOWX8rRFwXo53Vlm56w30y4rP0QLUsTCwfhSFhf+Yws5NNywYWqBnnXK mVZM0pTE35fwCrrzaBt07xCdcbJRsIX3hDvKMpwYJPFp7dwLXBlNEaBX5IfwxY35WVHP 8KHA== X-Gm-Message-State: AOAM531BfGKN9EVTFCesPMRzfg/hmQPch8VwbT7pdWOpzX41M1voUs0H xKq3MyXJ78oyZbPke76foSK7+g== X-Google-Smtp-Source: ABdhPJzhf1OaJMjLkOM/kIo9B/w+IVVstmRNwiiT3o0BYEzrLaeYNmmFs/II0q2QK/wS8jLuCzKsuA== X-Received: by 2002:a65:6910:: with SMTP id s16mr282728pgq.270.1628145318236; Wed, 04 Aug 2021 23:35:18 -0700 (PDT) Received: from google.com ([2401:fa00:9:211:8490:30e3:f52b:e185]) by smtp.gmail.com with ESMTPSA id z15sm6184331pgc.13.2021.08.04.23.35.15 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 04 Aug 2021 23:35:17 -0700 (PDT) Date: Thu, 5 Aug 2021 16:35:05 +1000 From: Matthew Bobrowski To: Gabriel Krisman Bertazi Cc: mtk.manpages@gmail.com, linux-man@vger.kernel.org, linux-api@vger.kernel.org, Amir Goldstein , Jan Kara Subject: Re: [PATCH v2] fanotify.7, fanotify_mark.2: Document FAN_FS_ERROR Message-ID: References: <20210804161024.3578338-1-krisman@collabora.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20210804161024.3578338-1-krisman@collabora.com> Precedence: bulk List-ID: X-Mailing-List: linux-man@vger.kernel.org On Wed, Aug 04, 2021 at 12:10:24PM -0400, Gabriel Krisman Bertazi wrote: > The kernel patches are not merged upstream, so please refrain from merging > it at the moment. This submission attempts to preview the interface > and gather some interface review. > > Cc: Amir Goldstein > Cc: Jan Kara > Cc: Matthew Bobrowski > Signed-off-by: Gabriel Krisman Bertazi > > --- > Changes since v1: > (Matthew) > - Grammar fixes > - Don't use the term "submitted" for events sent to the listener > - Clarify the kind of information that is file system specific > --- > man2/fanotify_mark.2 | 16 ++++++++++ > man7/fanotify.7 | 73 ++++++++++++++++++++++++++++++++++++++++++++ > 2 files changed, 89 insertions(+) > > diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 > index be3f72e040c0..2ae52f81d43b 100644 > --- a/man2/fanotify_mark.2 > +++ b/man2/fanotify_mark.2 > @@ -214,6 +214,22 @@ Create an event when a marked file or directory itself is deleted. > An fanotify group that identifies filesystem objects by file handles > is required. > .TP > +.BR FAN_FS_ERROR "(since Linux 5.15)" > +.\" commit WIP > +Create an event when a file system error is detected. > +A fanotify group that identifies filesystem objects by file handles ^ An > +is required. > +Support for this type of notification is done per-file system, > +but not every filesystem supports it. IMO, I think this would be clearer by saying something like: Support for such a notification type is dependent on the underlying filesystem. Not all filesystems support such notification types. ... Also, not sure whether this has already been considered, but it may be a good idea to keep/include a list of supported filesystems somewhere in the man-pages too. Understand that lists generally are hard to maintain moving forward and at some point in the future they tend to move a way from depicting what actually is the case. As in, something like: The filesystems that currently support FAN_FS_ERROR are: * ext4 Looks like this was something that was included in the kernel documentation side of things. > +A user can also expect to receive additional information > +in the form of a > +.BR FAN_EVENT_INFO_TYPE_ERROR > +record > +alongside the generic metadata event. > +See > +.BR fanotify (7) > +for additional details. > +.TP > .BR FAN_MOVED_FROM " (since Linux 5.1)" > .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 > Create an event when a file or directory has been moved from a marked > diff --git a/man7/fanotify.7 b/man7/fanotify.7 > index 6a7e70d75845..b8b7f44d4e32 100644 > --- a/man7/fanotify.7 > +++ b/man7/fanotify.7 > @@ -188,6 +188,24 @@ struct fanotify_event_info_fid { > .EE > .in > .PP > +In case of a FAN_FS_ERROR event, > +besides the file handle record, > +an additional record describing the error that occurred > +is included in the read buffer. There's mention of getting a bonus file_handle, but there's no mention of FAN_FS_ERROR being dependent on FAN_REPORT_FID. This needs to be corrected IMO. I think the most appropriate place to put this kind of detail would be in fanotify_mark(2) under the actual definition of FAN_FS_ERROR. I believe it'd also make sense to document what the behavior/status code of setting a mark on notification group without FAN_REPORT_FID actually is. > +The structure described below, will follow the generic > +.I fanotify_event_metadata > +structure within the read buffer: > +.PP > +.in +4n > +.EX > +struct fanotify_event_info_error { > + struct fanotify_event_info_header hdr; > + __s32 error; > + __u32 error_count; > +}; > +.EE > +.in > +.PP > For performance reasons, it is recommended to use a large > buffer size (for example, 4096 bytes), > so that multiple events can be retrieved by a single > @@ -311,6 +329,9 @@ A child file or directory was deleted in a watched parent. > .B FAN_DELETE_SELF > A watched file or directory was deleted. > .TP > +.B FAN_FS_ERROR > +A file-system error was detected. > +.TP > .B FAN_MOVED_FROM > A file or directory has been moved from a watched parent directory. > .TP > @@ -510,6 +531,32 @@ and the file handle is followed by a null terminated string that identifies the > name of a directory entry in that directory, or '.' to identify the directory > object itself. > .PP > +The fields of the > +.I fanotify_event_info_error > +structure are as follows: > +.TP > +.I hdr > +This is a structure of type > +.IR fanotify_event_info_header . > +and is a generic header that contains information used to > +describe an additional information record attached to the event. > +For > +.IR fanotify_event_info_error , > +.I info_type > +will have the value > +.BR FAN_EVENT_INFO_TYPE_ERROR . > +.I len > +has the size of the additional information record including the > +.IR fanotify_event_info_header > +itself. > +.TP > +.I error > +Identifies the file system specific error that occured s/occured/occurred > +.TP > +.I error_count > +This counts the number of errors suppressed This is a count of the number... > +since the last error was read. > +.PP > The following macros are provided to iterate over a buffer containing > fanotify event metadata returned by a > .BR read (2) > @@ -599,6 +646,32 @@ field. > In that case, the audit subsystem will log information about the access > decision to the audit logs. > .\" > +.SS Monitoring file systems for errors > +A single FAN_FS_ERROR event is stored by the kernel at once. This has to be a single FAN_FS_ERROR event per object? If so, I think we'd need to make that clear here. > +Extra error messages are suppressed and accounted for > +inside the current FAN_FS_ERROR event record, > +but details about the errors are lost. > +.PP > +Error types reported by FAN_FS_ERROR are file system specific > +and not all kinds of errors are reported by all file system. ... not all kinds of error types are reported by all filesystems. > +Refer to the file system documentation > +for additional information on the type of errors that are reported, > +and the meaning of those errors. > +.PP > +Errors not directly related to a file (i.e. super block corruption) > +are reported with an invalid > +.IR file_handle . > +For these errors, the > +.I file_handle > +will have the field > +.I handle_type > +set to > +.BR FILEID_INVALID , > +and the > +.I f_handle > +buffer set to > +.BR 0 . > +.\" This might strick controversy, but for the sake of keeping things consistent in this man page (as neither are really wrong), let's generally stick with the following throughout the supplied updates: s/{file system, file-system}/filesystem :P /M