linux-kernel - Re: How to document dimension units for virtual files?

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <OFA94CF0D3.C5318A12-ON42257211.004B4AC4-42257211.004E4728@de.ibm.com>
Date:	Tue, 24 Oct 2006 16:15:00 +0200
From:	Michael Holzheu <HOLZHEU@...ibm.com>
To:	Ingo Oeser <ioe-lkml@...eria.de>
Cc:	linux-kernel@...r.kernel.org, mschwid2@...ibm.com
Subject: Re: How to document dimension units for virtual files?

Hi Ingo,

Ingo Oeser <ioe-lkml@...eria.de> wrote on 10/23/2006 09:03:32 PM:

[snip]

> > 2. Encode dimension unit into filename (e.g. onlinetime_ms or
memory_kb)
>
> This is the recommended one.
> - simple to implement and understand on both sides
>
> - if you change units, you notice breaking userspace immediately
>   and can even notice it being used in closed source tools
>   with a simple strace
>
> - no parsing involved, as the author of the user space tool
>   usually assumes the unit implicitly (like "programming by contract",
where
>   the "contract" is the filename, which is quite easy to check for.
>
> - you can keep a legacy interface with neglible effort and code wastage
>
> - many advantages I forgot :-)
>

I also think that this is the best solution. It would be nice to have
that documented somewhere. Maybe in the Documentation directory
something like:

Howto export data in virtual files
==================================

If you want to export data to userspace via virtual filesystems
like procfs, sysfs, debugfs etc., the following rules are recommended:

- Export only one value in one virtual file.
- Data format should be as simple as possible.
- Use ASCII formated strings, no binary data if possible.
- If data has dimension units, encode that in the filename.
  Please use the following suffixes:
  * kb: Kilobytes
  * mb: Megabytes
  * ms: Milliseconds
  * us: Microseconds
  * ns: Nanoseconds
  * ...

Examples:
---------
> ls /sys/mydata
memory_kb
online_time_ms

> cat /sys/mydata/memory_kb
4769

Michael

-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/