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

[SourceForge.net]

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

Category: Documentation
Group: Python 2.3
Status: Open
Resolution: None
Priority: 5
Submitted By: Steven (grayshark)
Assigned to: Fred L. Drake, Jr. (fdrake)
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: Dima Dorfman (ddorfman)
Date: 2004-08-18 09: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