DosSetRelMaxFH()--Change Maximum Number of File Descriptors

 #define INCL_DOSERRORS
 #define INCL_DOSFILEMGR
 #include <os2.h>

 APIRET APIENTRY  DosSetRelMaxFH(PLONG pcbReqCount,
                                PULONG pcbCurMaxFH);  

The DosSetRelMaxFH() function requests that the system change the maximum number of file descriptors for the calling process (job). The system preserves all file descriptors that are currently open.

A request to increase the maximum number of file descriptors by more than the system can accommodate will succeed. The resulting maximum will be the largest number possible, but will be less than what you requested.

A request to decrease the maximum number of file descriptors will succeed. The resulting maximum will be the smallest number possible, but may be more than what you expected. For example, assume that the current maximum is 200 and there are 150 open files. A request to decrease the maximum by 75 results in the maximum being decreased by only 50, to 150, to preserve the open file descriptors.

A request to decrease the maximum number of file descriptors to below 20 will succeed, but the maximum will never be decreased below 20.

To retrieve the current maximum number of file descriptors, without any side effects, the value pointed to by pcbReqCount should be set to zero.

Parameters

pcbReqCount

(Input) A pointer to the number to be added to the maximum number of file descriptors for the calling process. If the value pointed to by pcbReqCount is positive, the system increases the maximum number of file descriptors. If the value pointed to by pcbReqCount is negative, the system decreases the maximum number of file descriptors.

pcbCurMaxFH

(Output) A pointer to the location to receive the new total number of allocated file descriptors.

Authorities

No authorization is required.

Return Value

NO_ERROR (0)

DosSetRelMaxFH() was successful. The function returns NO_ERROR (0) even if the system disregards or partially fulfills a request for an increase or a decrease (for example, decreasing by a smaller number than requested). You should examine the value pointed to by pcbCurMaxFH to determine the result of this function.

value (non-zero)

DosSetRelMaxFH() was not successful. The value that is returned indicates the error.

Error Conditions

If DosSetRelMaxFH() is not successful, the value that is returned is one of the following errors. The <bseerr.h> header file defines these values.

[ERROR_GEN_FAILURE]

A general failure occurred.

This may result from damage in the system. See messages in the job log for other possible causes.

[ERROR_PROTECTION_VIOLATION]

A protection violation occurred.

A pointer passed to this function is not a valid pointer.

Error Messages

The system may send the following messages from this function.

Usage Notes

1. If you are using the select() API, you should be aware of the value of the FD_SETSIZE macro defined in the <sys/types.h> header file. This value is defined to be 200. This means that the fd_set structure is defined to contain 200 bits, one for each file descriptor.

   If your application uses DosSetRelMaxFH() to increase the maximum number of file descriptors beyond 200, you should consider defining your own value for the FD_SETSIZE macro prior to including <sys/types.h>. This is to ensure that the fd_set structure is defined with the correct number of bits to accommodate the actual maximum number of file descriptors.

2. The maximum number of file descriptors for this process may be obtained by using the sysconf() API with the _SC_OPEN_MAX parameter.
   
   
3. If this function is called by a thread executing one of the scan-related exit programs (or any of its created threads), it will fail with error code [ERROR_GEN_FAILURE]. See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs for more information.

Related Information

• The <os2.h> file (see Header Files for UNIX^®-Type Functions)
  
• The <os2def.h> file (see Header Files for UNIX-Type Functions)
  
• The <bse.h> file (see Header Files for UNIX-Type Functions)
  
• The <bsedos.h> file (see Header Files for UNIX-Type Functions)
  
• The <bseerr.h> file (see Header Files for UNIX-Type Functions)
  
• The <sys/types.h> file (see Header Files for UNIX-Type Functions)
  
• select()--Wait for Events on Multiple Sockets
  
• sysconf()--Get System Configuration Variables

Example

The following example increases the maximum number of file descriptors by two.

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#define INCL_DOSERRORS
#define INCL_DOSFILEMGR
#include <os2.h>
#include <stdio.h>

void main()
{
 long  ReqCount = 0; /* Number to add to maximum */
                     /* file descriptor count.  */
 ulong CurMaxFH;     /* New count of file descriptors. */
 int   rc;           /* Return code. */

 /* Find out what the initial maximum is.*/
 if ( NO_ERROR == (rc = DosSetRelMaxFH(&ReqCount, &CurMaxFH)))
 {
  printf("Initial maximum = %d",CurMaxFH);

  ReqCount = 2; /* Set up to increase by 2. */

  if (NO_ERROR == (rc = DosSetRelMaxFH(&ReqCount, &CurMaxFH)))
  {
   printf("    New maximum = %d",CurMaxFH);
  }
 }
 if (NO_ERROR != rc)
 {
  printf("Error = &d",rc);
 }
}

Output:

Initial maximum = 200    New maximum = 202

[ Back to top | UNIX-Type APIs | APIs by category ]