From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1751573AbdKUQGH (ORCPT <rfc822;w@1wt.eu>);
        Tue, 21 Nov 2017 11:06:07 -0500
Received: from mail-pf0-f182.google.com ([209.85.192.182]:39627 "EHLO
        mail-pf0-f182.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
        with ESMTP id S1751189AbdKUQGF (ORCPT
        <rfc822;linux-kernel@vger.kernel.org>);
        Tue, 21 Nov 2017 11:06:05 -0500
X-Google-Smtp-Source: AGs4zManUk29h6wHkCP1Zh/F+O7UUuvHQkXbdaxJM2JO0YXFs1WPZvBsHfcQ95uQfneAQOPZywOPoA==
Date: Tue, 21 Nov 2017 08:06:01 -0800
From: Richard Cochran <richardcochran@gmail.com>
To: Arnd Bergmann <arnd@arndb.de>
Cc: Michael Kerrisk <mtk.manpages@gmail.com>,
        Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
        Linux API <linux-api@vger.kernel.org>,
        John Stultz <john.stultz@linaro.org>,
        Thomas Gleixner <tglx@linutronix.de>,
        Stephen Boyd <sboyd@codeaurora.org>
Subject: Re: [PATCH] [man-pages] adjtimex.2: document clock_adjtime
Message-ID: <20171121160601.2xti5ho5pul2v7tm@localhost>
References: <20171120225302.3379657-1-arnd@arndb.de>
 <20171121030459.swng4eyke34uf3sv@localhost>
 <CAK8P3a1TFPNE+A5Gf=cgsxiqi2VQOzfRLUgirjNtb6Tdei0Ovg@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <CAK8P3a1TFPNE+A5Gf=cgsxiqi2VQOzfRLUgirjNtb6Tdei0Ovg@mail.gmail.com>
User-Agent: NeoMutt/20170113 (1.7.2)
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On Tue, Nov 21, 2017 at 09:06:37AM +0100, Arnd Bergmann wrote:
> 
> I copied that line from clock_gettime() man page. I suppose we want to
> fix change this in both pages, right? Any suggestions for a good way to
> express your explanation in the man page? I suppose we don't want to
> go into details of the implementation there but still capture the possible
> corner cases.

Dynamic clockids are a Linux specific extension.  This should be
explained with a paragraph or two on the gettime man page, along with
an example using the macros.

	#define CLOCKFD 3
	#define FD_TO_CLOCKID(fd)	((~(clockid_t) (fd) << 3) | CLOCKFD)
	#define CLOCKID_TO_FD(clk)	((unsigned int) ~((clk) >> 3))

Then, the adjtimex page can say, see gettime.

Let me try to come up with a text over the (USA) holiday weekend.

Thanks,
Richard