__fsetlocking() — Set locking type

Standards

Standards / Extensions	C or C++	Dependencies
Language Environment	both	None

Format

#include <stdio.h>
#include <stdio_ext.h>

int __fsetlocking(FILE *stream, int type);

General description

The __fsetlocking() function allows the type of locking on an open stream to be controlled or queried by the application.

If type is FSETLOCKING_INTERNAL, subsequent stdio functions perform implicit locking around every operation on the given stream. This is the default system behavior.

If type is FSETLOCKING_BYCALLER, subsequent stdio functions assume that the caller is responsible for maintaining the integrity of the stream in the face of access by multiple threads. If only one thread is accessing the stream, nothing further needs to be done. If multiple threads are accessing the stream, you can use the flockfile(), funlockfile(), and ftrylockfile() functions to provide the appropriate serialization.

If type is FSETLOCKING_QUERY, the __fsetlocking() function returns the current locking type of the stream without changing it.

Usage notes

The _fsetlocking() function acts upon FILE* objects. It is possible to have the same physical file represented by multiple FILE* objects that are not recognized as being equivalent. For example, fopen() opens a file in thread A and sets the locking type as FSETLOCKING_INTERNAL. Then fopen() opens the same file in another thread B and sets the locking type as FSETLOCKING_BYCALLER. If both threads begin to write to their FILE* objects, the results are unpredictable.
The __fsetlocking() function impacts the behavior of all other stream operation functions. Using __fsetlocking() to modify the locking type while any of these stream operation functions are executing might produce undesirable behaviors, including hang conditions. You must make sure that __fsetlocking() is used only when no other functions are acting upon the stream.

Returned value

The __fsetlocking() function returns the locking type in effect before the call to __fsetlocking().

The __fsetlocking() function returns -1 if the stream or the locking type is not valid and sets errno to nonzero.

Error Code: Description
EBADF: The stream specified by stream is not valid.
EINVAL: The locking type is not valid.

Example

CELEBF85

/* CELEBF85

   This example sets LOCKING_TYPE as locking type to a stream.

   It checks that the fopen() function is successful and that
   locking type is setted to the stream and queried from the stream.

*/

#include <stdio.h>
#include <stdio_ext.h>

int main(void)
{
   FILE *stream;
   int locktype;
   int nwrite;
   int buflen;
   char buf[5]="1234";

   if((stream = fopen("myfile.dat", "w+b")) != NULL )
   {
      locktype = __fsetlocking(stream,FSETLOCKING_BYCALLER);
      locktype = __fsetlocking(stream,FSETLOCKING_QUERY);
      if(locktype == FSETLOCKING_BYCALLER){
         printf("__fsetlocking succeeds! \
         Lock type is FSETLOCKING_BYCALLER\n");
      }
      buflen = strlen(buf);
      flockfile(stream);
      nwrite = fwrite(buf, 1, buflen, stream);
      if(nwrite < buflen){
         printf("fwrite did not return expected number of bytes\n");
      }
      funlockfile(stream);
   }
   return(0);
}

Output

__fsetlocking succeeds! Lock type is FSETLOCKING_BYCALLER