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►  ◄Changes►               ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSMEMMGR
 
USHORT DosAllocSeg(usSize, psel, fsAttr)
USHORT usSize;    /* number of bytes requested                  */
PSEL psel;        /* pointer to variable for selector allocated */
USHORT fsAttr;    /* shareable/discardable flags                 */
 
The DosAllocSeg function allocates a memory segment and copies the segment
selector to a specified variable.
 
The DosAllocSeg function can specify that segments can be shared by other
processes. If the SEG_GETTABLE flag is used, other processes can gain access
to the shared memory by calling the DosGetSeg function. If the SEG_GIVEABLE
flag is used, the memory can be shared by other processes after the process
allocating the memory has called the DosGiveSeg function. In both cases, the
process allocating the memory must pass the selector to the process that
will share the memory.
 
The DosAllocSeg function is a family API function.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
usSize     Specifies the number of bytes to allocate. This number can be any
           value in the range 0 through 65,535. If this value is zero, the
           function allocates 65,536 bytes.
 
psel       Points to the variable that receives the segment selector.
 
fsAttr     Specifies the segment attributes. This parameter can be one or
           more of the following values:
 
           Value            Meaning
           ─────────────────────────────────────────────────────────────────
           SEG_DISCARDABLE  Creates a discardable, nonshareable segment.
                            Once the segment is unlocked, it may be
                            discarded to satisfy another memory-allocation
                            request.
 
           SEG_GETTABLE     Creates a shareable segment that other processes
                            can retrieve by using the DosGetSeg function.
 
           SEG_GIVEABLE     Creates a shareable segment that the owning
                            process can give to other processes by using the
                            DosGiveSeg function.
 
           SEG_NONSHARED    Creates a nonshareable, nondiscardable segment.
                            This value cannot be combined with any other
                            value.
 
           SEG_SIZEABLE     Specifies that a shared segment can be reduced
                            in size by DosReallocSeg.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be the following:
 
     ERROR_NOT_ENOUGH_MEMORY
 
Comments
 
If the SEG_DISCARDABLE attribute is set, the DosAllocSeg function
automatically locks the segment. The segment cannot be discarded until the
DosUnlockSeg function is called. Before a process accesses an unlocked
discardable segment, it must call the DosLockSeg function to determine
whether the segment has been discarded, and to prevent the segment from
being discarded while the process is accessing it.
 
If necessary, the system will discard an unlocked discardable segment in
order to satisfy another allocation request. The new allocation request can
come from any process, including the process that allocated the segment
being discarded.
 
The DosFreeSeg function frees the segment. If the segment was declared as
shareable, it will not be discarded from memory until the last process using
it calls DosFreeSeg.
 
The DosAllocSeg function can allocate only up to 64K of contiguous memory.
To allocate more than 64K, use the DosAllocHuge function.
 
DosAllocSeg can be issued from ring 2, but the segment will be allocated as
a ring-3 segment.
 
Restrictions
 
In real mode, the following restrictions apply to the DosAllocSeg function:
 
♦  The usSize parameter is rounded up to the next paragraph (16-byte)
   value.
 
♦  The actual segment address is copied to the psel parameter.
 
Example
 
This example calls the DosAllocSeg function to allocate 26,953 bytes. It
then converts the selector to a far pointer that can access the allocated
bytes.
 
PCH pchBuffer;
SEL sel;
 
DosAllocSeg(26953,            /* bytes to allocate            */
    &sel,                     /* address of selector          */
    SEG_NONSHARED);           /* sharing flag                 */
pchBuffer = MAKEP(sel, 0);    /* converts selector to pointer */
 
See Also
 
DosAllocHuge, DosAllocShrSeg, DosFreeSeg, DosGetSeg, DosGiveSeg, DosLockSeg,
DosReallocSeg, DosUnlockSeg
 
                                      ♦