Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSFILEMGR
 
USHORT DosChgFilePtr(hf, lDistance, fMethod, pulNewPtr)
HFILE hf;            /* file handle          */
LONG lDistance;      /* distance to move     */
USHORT fMethod;      /* method of moving     */
PULONG pulNewPtr;    /* new pointer location */
 
The DosChgFilePtr function moves the file pointer to a new position in the
file. The file pointer is maintained by the system. It points to the next
byte to be read from a file or to the next position in the file to receive a
byte.
 
The DosChgFilePtr function is a family API function.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hf         Identifies the file. This handle must have been created
           previously by using the DosOpen function.
 
lDistance  Specifies the number of bytes to move the file pointer in the
           file. If this value is positive, the pointer moves forward
           through the file. If the value is negative, the pointer moves
           backward.
 
fMethod    Specifies where the move will start. This parameter must be one
           of the following values:
 
           Value         Meaning
           ─────────────────────────────────────────────────────────────────
           FILE_BEGIN    Start move at the beginning of the file.
 
           FILE_CURRENT  Start move at the current location.
 
           FILE_END      Start move at the end of the file.
 
pulNewPtr  Points to the long variable that receives the new file-pointer
           location.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_INVALID_FUNCTION
     ERROR_INVALID_HANDLE
     ERROR_SEEK_ON_DEVICE
 
Comments
 
The system automatically advances the file pointer for each byte read or
written; the pointer is at the beginning of the file when the file is
opened.
 
Example
 
This example opens the file abc for read and write access, calls the
DosChgFilePtr function to set the file pointer at the end of the file,
writes the string "Hello World", and closes the file. The ulFilePointer
variable contains the file's current length when the pointer is at the end
of the file.
 
HFILE hf;
USHORT usAction, cbBytesWritten;
ULONG ulFilePointer;
DosOpen("abc", &hf, &usAction, 0L, FILE_NORMAL,
    FILE_OPEN | FILE_CREATE,
    OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYWRITE, 0L);
DosChgFilePtr(hf,                    /* file handle             */
    0L,                              /* distance to move        */
    FILE_END,                        /* type of movement        */
    &ulFilePointer);                 /* address of new position */
DosWrite(hf, "Hello World\r\n", 13, &cbBytesWritten);
DosClose(hf);
 
See Also
 
DosNewSize, DosOpen, DosRead, DosWrite
 
                                      ♦