[ python-Bugs-1008310 ] os.major() os.minor() example and description change

[SourceForge.net]

Bugs item #1008310, was opened at 2004-08-12 15:21
Message generated for change (Comment added) made by nnorwitz
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1008310&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Python 2.3
>Status: Closed
>Resolution: Fixed
Priority: 5
Submitted By: Steven (grayshark)
>Assigned to: Neal Norwitz (nnorwitz)
Summary: os.major() os.minor() example and description change

Initial Comment:
The description for os.major() and os.minor() are damn
poor.
major(  	device)
    Extracts a device major number from a raw device
number. New in version 2.3. 

minor( 	device)
    Extracts a device minor number from a raw device
number. New in version 2.3. 

The really bad part is the term "raw device number". 

it should be:
Extracts a device [major,minor] number for stat st_rdev
field, or returns a zero if the st_rdev does not
reference a special block device.

Example follows.

----------------------------------------------------------------------

>Comment By: Neal Norwitz (nnorwitz)
Date: 2005-10-02 22:48

Message:
Logged In: YES 
user_id=33168

Thanks.  I tweaked the wording slightly, based on both of
the comments.  I tried to make it a bit more descriptive and
allude to the system dependent behaviour:

Extracts the device major number from a raw device number
(usually \member{st_dev} or \member{st_rdev} field from
\ctype{stat}).

Let me know if there are any more suggestions.

Checked in as:
 * Doc/lib/libos.tex 1.169, 1.146.2.12

----------------------------------------------------------------------

Comment By: Dima Dorfman (ddorfman)
Date: 2004-08-18 02:56

Message:
Logged In: YES 
user_id=908995

The proposed description is incorrect. st_rdev is not the
only place to get this value; st_dev comes to mind, and
those interested in these values are likely to be playing
with other system interfaces anyway, so implying a coupling
with st_rdev would be a mistake. I haven't found any
documentation suggesting that major and minor return 0 if
the input is invalid, and since none of these operations are
standardized, we shouldn't document what are platform-
specific semantics. My recent posting on the topic to
comp.lang.python ("using os.major") said, in part,

  The documentation for os.stat mentions st_rdev, but it
  doesn't call it the "raw" device number. The FreeBSD
  documentation is about evenly split on calling it the "raw
  device number" or the "device ID", but Posix uses the
  latter, and I think that makes more sense. There's nothing
  raw about this value; I think it's only "raw" compared to
  internal kernel structures, where a device could be a
  pointer to struct instead of an integer (it's certainly
  not more raw than st_dev, which has the same type).

Accordingly, it might be good to change the documentation
for all of these things to consistently use the term "device
ID" instead of "raw device number". That might still be
poor, but it's as much as can be said for these operations
on all platforms. I'll submit a patch for that in a few days
unless someone beats me to it.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1008310&group_id=5470