[ python-Bugs-1460564 ] Misleading documentation for socket.fromfd()

[SourceForge.net]

Bugs item #1460564, was opened at 2006-03-29 04:41
Message generated for change (Comment added) made by mikeh-id
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1460564&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: Python Library
Group: None
Status: Open
Resolution: None
Priority: 5
Submitted By: Michael Smith (mlrsmith)
Assigned to: Nobody/Anonymous (nobody)
Summary: Misleading documentation for socket.fromfd()

Initial Comment:
The socket.fromfd() method does not correctly document
what it does, in a way that is likely to cause users to
leak file descriptors.

Proposed fix:

--- Modules/socketmodule.c      2005-09-14
20:15:03.000000000 +0200
+++
/home/msmith/src/Python-2.4.2/Modules/socketmodule.c  
     2006-03-29 11:28:35.000000000 +0200
@@ -3077,7 +3077,8 @@
 PyDoc_STRVAR(fromfd_doc,
 "fromfd(fd, family, type[, proto]) -> socket object\n\
 \n\
-Create a socket object from the given file descriptor.\n\
+Duplicate the given file descriptor, and create a
socket\n\
+object from the duplicate.\r\
 The remaining arguments are the same as for socket().");

 #endif /* NO_DUP */


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

Comment By: Mike Howard (mikeh-id)
Date: 2006-03-31 12:49

Message:
Logged In: YES 
user_id=1195975

I don't believe the comment is incorrect, but I think the
code should be changed to reflect the comment.

socket.fromfd() is designed to be used when stdin/out/err
are inhereted from an invoking process - most probably
inetd.  In this case, we get a file descriptor for an entity
which is really a socket and we need a socket in order to
perform i/o properly.  Consequently, I think it is an error
to dup() the fd within 'fromfd'.



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

Comment By: Michael Smith (mlrsmith)
Date: 2006-03-31 12:12

Message:
Logged In: YES 
user_id=1488997

It is not an error to dup() the fd here, but it IS behaviour
that the process calling socket.fromfd() must know about. 

Also, changing this behaviour will probably break most users
of this API, since I don't see any way to use it correctly
without knowing that it does, in fact, dup() the FD (my code
reviously leaked file descriptors because I didn't know
this). Breaking existing applications is bad, hence my
suggestion to augment the documentation.

FWIW: my app receives file descriptors - which are sockets -
over a unix socket using sendmsg/recvmsg, for which I have
an extension written in C. Using socket.fromfd() on this FD
works perfectly, but I need to then os.close(fd) the
original FD to avoid leaking it.



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

Comment By: Mike Howard (mikeh-id)
Date: 2006-03-31 11:52

Message:
Logged In: YES 
user_id=1195975

I don't believe the comment is incorrect, but I think the
code should be changed to reflect the comment.

socket.fromfd() is designed to be used when stdin/out/err
are inhereted from an invoking process - most probably
inetd.  In this case, we get a file descriptor for an entity
which is really a socket and we need a socket in order to
perform i/o properly.  Consequently, I think it is an error
to dup() the fd within 'fromfd'.



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

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