The docs for resource.setrlimit (http://docs.python.org/2.7/library/resource.html#resource.setrlimit) state: "The limits argument must be a tuple (soft, hard) of two integers describing the new limits. A value of -1 can be used to specify the maximum possible upper limit."

On Mac OSX (10.7.5) with Python 2.7.3 (built fresh), I get the following behaviour:


$ PATH=$HOME/test/bin:$PATH DYLD_LIBRARY_PATH=$HOME/test/lib:$DYLD_LIBRARY_PATH python
Python 2.7.3 (default, Mar 13 2013, 11:02:56) 
[GCC 4.2.1 (Based on Apple Inc. build 5658) (LLVM build 2336.9.00)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import resource
>>> resource.setrlimit(resource.RLIMIT_NOFILE, (10, -1))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: not allowed to raise maximum limit
>>> resource.setrlimit(resource.RLIMIT_NOFILE, (10, 10))
>>> 


I get the same behaviour for the system python (2.7.3 built with GCC 4.6.3) in Ubuntu 12.04.1.

Since it says "maximum possible limit", I think -1 is the maximum system limit, not the maximum value a particular process is allowed to use.  If that is true the error message is presumably accurate.  And if that's true it needs to be clarified in the docs...and perhaps an enhancement request added.  But my guess might be wrong, too.

Module 'resource' is unix only.  What happens on 3.x or linux?

Given that the doc invites input of -1, it seems to me that raising an exception is wrong; -1 should be interpreted as a valid value.

On Fedora 17, x86_64

./python 
Python 3.4.0a0 (default:fb50eb64e097, Feb 22 2013, 11:43:18) 
[GCC 4.7.2 20120921 (Red Hat 4.7.2-2)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import resource
[92450 refs, 32257 blocks]
>>> resource.setrlimit(resource.RLIMIT_NOFILE, (10, -1))
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: not allowed to raise maximum limit

The OSX manpage for setrlimit includes:

COMPATIBILITY
     setrlimit() now returns with errno set to EINVAL in places that histori-
     cally succeeded.  It no longer accepts "rlim_cur = RLIM_INFINITY" for
     RLIM_NOFILE.  Use "rlim_cur = min(OPEN_MAX, rlim_max)".

It's strange that this is not mentioned in the corresponding manpage on Ubuntu 12.04.

It seems the reason we can't use -1 for RLIMIT_NOFILE is because this requests 'unlimited' (RLIM_INFINITY), while there is always a limit on the number of open files (e.g., OPEN_MAX).

Looking at the code (Modules/resource.c), python is doing the sensible thing.  It seems that resource.setrlimit would have to be special-cased for RLIMIT_NOFILE to work as documented when specifying a "-1", but then python would be diverging from the behaviour of the underlying system call.

I therefore propose that the documentation simply be adjusted to note the observed behaviour (i.e., specifying -1 means 'unlimited', and does not work in general for RLIMIT_NOFILE).  I would be happy to provide a patch if this is desired.

That would be great, thanks.

Not sure how you want patches formatted, so I went for 'git format-patch'.

Also, this is my first attempt at writing ReST and my first attempt at writing docs for Python, so you may want to double-check I didn't screw up the syntax or style.  Hopefully this doesn't cause more work than writing it yourself....

P.S. This is relative to the 'default' branch in the public cpython.

Thanks for the patch.  You got the patch mechanics correct.

I did a little experimenting, and at least on my linux box, the exception is raised for any(*) resource whose hard limit is not unlimited.  I'm attaching a revised patch that expresses this.  Do you think this provides sufficient clarification?

One question I have relates to the use of the word 'infinite'.  In the shell, the term 'unlimited' is used, so I'm thinking that's what most people will be familiar with.  On the other hand, the man page for the syscall we are wrapping uses the term 'infinite', so one can argue that it is more correct.  I'm ambivalent about which term to use.

(*) I tested this on NO_PROC, since that's the only other one my shell has a hard limit for, and by setting a hard limit via the shell ulimit command and then using (-1, -1) in the setrlimit call.

That's good; it doesn't have what I added to the description of RLIMIT_NOFILE, but perhaps you chose to leave that out on purpose.

Since both "unlimited" and "infinite" are both used in different contexts, perhaps we should use both, e.g., "infinite/unlimited"?

infinite/unlimited sounds like a good compromise :)

Yes, I left NOFILE out on purpose, because the issue applies to any resource that is not unlimited for whatever reason.

Here's another attempt, using infinite/unlimited .  I noticed that the following paragraph talks specifically about the error raised, so I moved the explanation to that paragraph.

You missed out an "is":

   Raises :exc:`ValueError` if an invalid resource is specified, if the new soft
   limit exceeds the hard limit, or if a process tries to raise its hard limit
   (unless the process has an effective UID of super-user).  Specifying an
   infinite/unlmited limit when the hard or system limit for that resource **is** not
   unlimited will result in a :exc:`ValueError`.  ``setrlimit`` may also raise
    :exc:`error` if the underlying system call fails.

in-finite literally means un-limited or un-bounded. However, 'infinte' has also taken on the meaning of 'actual infinity'. So in my algorithms book, when 'actual infinities' are not in play. I describe the set of counts as unbounded. I suggest you go with just 'unlimited'. I believe constructions such as and/or (which some style guides discourage. because they are a bit ugly) should suggest some contrast or difference, rather than exact synonyms but I could be wrong.

Terry: well, we're trying to deal with the fact that the setrlimit man page says:

       The  value  RLIM_INFINITY  denotes  no limit on a resource (both in the
       structure returned by getrlimit() and in the structure passed to  setr-
       limit()).

Oh.  RLIM_INFINITY is defined in the module.  Let me update the patch again :)

Here's a patch that adds RLIMIT_INFINITY and uses it.  This constant exists in 2.7 and Python3, but has not been previously documented.

Both old and new have this sentence:
"Raises :exc:`ValueError` if an invalid resource is specified, if the new soft limit exceeds the hard limit, or if a process tries to raise its hard limit (unless the process has an effective UID of super-user)."

This strikes me as a bit awkward and ambiguous. As a naive reader that does not already know the facts, it is unclear whether the (unless...) applies to the overall sentence (Raise...) or just the last clause (if a process...). I would try moving the 'unless...' either before the whole sentence or before the clause, depending on which is true.

How about this.

New changeset 186f6bb3e46a by R David Murray in branch '3.3':
#17409: Document RLIM_INFINITY and use it to clarify the setrlimit docs.
http://hg.python.org/cpython/rev/186f6bb3e46a

New changeset 9c4db76d073e by R David Murray in branch '2.7':
#17409: Document RLIM_INFINITY and use it to clarify the setrlimit docs.
http://hg.python.org/cpython/rev/9c4db76d073e

New changeset f1d95b0ab66e by R David Murray in branch 'default':
Merge #17409: Document RLIM_INFINITY and use it to clarify the setrlimit docs.
http://hg.python.org/cpython/rev/f1d95b0ab66e

There being no objection :) I've committed the patch.

Thanks!