[an error occurred while processing this directive]
Node:<a name="Move%20structs">Move structs</a>,
Next:<a rel=next href="faq18_6.html">Fat DS</a>,
Previous:<a rel=previous href="faq18_4.html">Xfer</a>,
Up:<a rel=up href="faq18.html">Low-level</a>
<br>

<h2>18.5 How to move structs returned by real-mode services?</h2>

<p><em><strong>Q</strong>: My program uses the contents of a structure returned by a VBE
function, but some of the struct members are garbled!</em>

<br><p>
<p><strong>A</strong>: Most probably, this happens because of incorrect declaration of
the structure in your program.  Many people copy a declaration from some
real-mode program, and that is exactly what gets them into trouble.

<p>Here are some gotchas in this context:

<ul>
<li>The structure should be declared with <code>__attribute__((packed))</code>, to
prevent GCC from inserting gaps between some members to make them
properly aligned for faster access (see <a href="faq22_11.html">how gcc aligns structs</a>).  C programs can
declare the entire struct with the packed attribute, but C<tt>++</tt>
programs will need to declare each member with it, see <a href="faq22_11.html">__attribute__((packed))</a>.

<li>If the real-mode struct has members which are pointers, you need to
replace each pointer with a pair of an offset and a segment (in that
order, due to Intel's little-endian byte order).  This is because
real-mode far pointers cannot be used as protected-mode pointers: you
cannot dereference them to get access to the object they point to. 
Declaring them as a segment:offset pair will force you into correct
usage, as shown below.

<li>To use pointers which are members of the structure, you will have to
employ some of the methods described in <a href="faq18_4.html">section about using the transfer buffer</a>.  For example, to copy data whose real-mode address
is returned in a struct, use <code>dosmemget</code> or one of the
<code>_farpeekX</code> family of functions in conjunction with the
<code>_dos_ds</code> selector, and don't forget to compute the linear address
as <code>segment * 16 + offset</code>, where <code>segment</code> and <code>offset</code>
are taken from the struct members converted from the far pointers in the
original real-mode code.

<li>If the pointer is to a function, you will need to use the library
function <code>__dpmi_simulate_real_mode_procedure_retf</code> to call it
(don't forget to zero out the <code>.x.ss</code> and <code>.x.sp</code> members of
the <code>__dpmi_regs</code> structure!).  See <a href="faq18_3.html">real-mode functions</a>.

<li>Many real-mode compilers use 16-bit <code>int</code>s, whereas in DJGPP, an
<code>int</code> is 32-bit wide.  You need to change the declaration of all
struct members from <code>int</code> to <code>short</code>, and from <code>unsigned</code>
to <code>unsigned short</code>. 
</ul>

<p>For example, the following real-mode structure declaration:

<pre> struct ncb {
   unsigned ncb_command;
   int ncb_status;
   char far *ncb_buffer;  /* a far pointer to a buffer */
   char ncb_name[32];
   int far (*ncb_dispatch)();  /* a pointer to a far function */
 };
</pre>

<p>should be converted to this in a DJGPP program:

<pre> struct ncb {
   unsigned short ncb_command __attribute__((packed));
   short ncb_status __attribute__((packed));
   unsigned short ncb_buf_offset __attribute__((packed));
   unsigned short ncb_buf_segment __attribute__((packed));
   char ncb_name[32] __attribute__((packed));
   unsigned short ncb_dispatch_offset __attribute__((packed));
   unsigned short ncb_dispatch_segment __attribute__((packed));
 };
</pre>

<p>With the above declaration of <code>struct ncb</code>, the following real-mode
code:

<pre> int status = ncb.ncb_status;
 int value  = *(int far *)ncb.buf[3];
</pre>

<p>should read in DJGPP:

<pre> short status, value;
 struct ncb ncb_struct

 /* Fetch the structure from the transfer buffer.  */
 dosmemget (__tb, sizeof (struct ncb), &amp;ncb_struct);
 status = ncb_struct.ncb_status;
 value  = _farpeekw (_dos_ds,
                     ncb_struct.ncb_buf_segment*16
                     + ncb_buf_offset + 3);
</pre>

<p>In other words, you need to add code that moves the structure to and
from the transfer buffer, and replace each pointer dereference with a
call to an appropriate <code>_farpeekX</code> or <code>_farpokeX</code> function.

<p><hr>
[an error occurred while processing this directive]