Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <io.h>
    int _open_osfhandle( long osfhandle, int access );

Description:
    The _open_osfhandle function allocates a POSIX-level file handle and
    sets it to point to the operating system's internal file handle
    specified by osfhandle.  The value returned by  _get_osfhandle can be
    used as an argument to the _open_osfhandle function.

    The access mode is established by a combination of the bits defined in
    the <fcntl.h> header file.  The following bits may be set:

    Mode     Meaning

O_RDONLY
    permit the file to be only read.

O_WRONLY
    permit the file to be only written.

O_RDWR
    permit the file to be both read and written.

O_APPEND
    causes each record that is written to be written at the end of the file.

O_CREAT
    has no effect when the file indicated by filename already exists;
    otherwise, the file is created;

O_TRUNC
    causes the file to be truncated to contain no data when the file exists;
    has no effect when the file does not exist.

O_BINARY
    causes the file to be opened in binary mode which means that data will
    be transmitted to and from the file unchanged.

O_TEXT
    causes the file to be opened in text mode which means that
    carriage-return characters are written before any linefeed character
    that is written and causes carriage-return characters to be removed when
    encountered during reads.

O_NOINHERIT
    indicates that this file is not to be inherited by a child process.

O_EXCL
    indicates that this file is to be opened for exclusive access.  If the
    file exists and  O_CREAT was also specified then the open will fail
    (i.e., use  O_EXCL to ensure that the file does not already exist).

    When neither  O_TEXT nor  O_BINARY are specified, the default value in
    the global variable  _fmode is used to set the file translation mode.
     When the program begins execution, this variable has a value of
     O_TEXT.

     O_CREAT must be specified when the file does not exist and it is to be
    written.

    When two or more manifest constants are used to form the flags argument,
    the constants are combined with the bitwise-OR operator (|).

    The example below demonstrates the use of the  _get_osfhandle and
    _open_osfhandle functions.  Note that the example shows how the  dup2
    function can be used to obtain almost identical functionality.

    When the POSIX-level file handles associated with one OS file handle are
    closed, the first one closes successfully but the others return an error
    (since the first call close the file and released the OS file handle).
     So it is important to call  close at the right time, i.e., after all
    I/O operations are completed to the file.

Returns:
    If successful, _open_osfhandle returns a POSIX-style file handle.
     Otherwise, it returns -1.

Example:
    #include <stdio.h>
    #include <stdlib.h>
    #include <io.h>
    #include <fcntl.h>

    void main()
    {
        long os_handle;
        int fh1, fh2, rc;

        fh1 = open( "file",
                    O_WRONLY | O_CREAT | O_TRUNC | O_BINARY,
                    S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP );
        if( fh1 == -1 ) {
            printf( "Could not open output file\n" );
            exit( EXIT_FAILURE );
        }
        printf( "First POSIX handle %d\n", fh1 );

    #if defined(USE_DUP2)
        fh2 = 6;
        if( dup2( fh1, fh2 ) == -1 ) fh2 = -1;
    #else
        os_handle = _get_osfhandle( fh1 );
        printf( "OS Handle %ld\n", os_handle );

        fh2 = _open_osfhandle( os_handle, O_WRONLY |
                                          O_BINARY );
    #endif
        if( fh2 == -1 ) {
            printf( "Could not open with second handle\n" );
            exit( EXIT_FAILURE );
        }
        printf( "Second POSIX handle %d\n", fh2 );

        rc = write( fh2, "trash\x0d\x0a", 7 );
        printf( "Write file using second handle %d\n", rc );

        rc = close( fh2 );
        printf( "Closing second handle %d\n", rc );
        rc = close( fh1 );
        printf( "Closing first handle %d\n", rc );
    }

Classification:
    WATCOM

Systems:
    All, Netware

See Also:
    close, dup2, fdopen, _get_osfhandle, _hdopen, open, _os_handle