doc/html/ref/fileio-sockets.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >Sockets</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="File System Support Infrastructure"
  23 HREF="fileio.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="Initialization and Mounting"
  26 HREF="fileio-mounting.html"><LINK
  27 REL="NEXT"
  28 TITLE="Select"
  29 HREF="fileio-select.html"></HEAD
  30 ><BODY
  31 CLASS="CHAPTER"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="fileio-mounting.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 ></TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="fileio-select.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="CHAPTER"
  82 ><H1
  83 ><A
  84 NAME="FILEIO-SOCKETS">Chapter 26. Sockets</H1
  85 ><P
  86 >If a network stack is present, then the FILEIO infrastructure also
  87 provides access to the standard BSD socket calls.</P
  88 ><P
  89 >The netstack table contains entries which describe the network
  90 protocol stacks that are in the system image. Each resident stack
  91 should export an entry to this table using the
  92 <TT
  93 CLASS="LITERAL"
  94 >NSTAB_ENTRY()</TT
  95 > macro.</P
  96 ><P
  97 >Each table entry has the following structure:</P
  98 ><TABLE
  99 BORDER="5"
 100 BGCOLOR="#E0E0F0"
 101 WIDTH="70%"
 102 ><TR
 103 ><TD
 104 ><PRE
 105 CLASS="PROGRAMLISTING"
 106 >struct cyg_nstab_entry
 107 {
 108     cyg_bool            valid;          // true if stack initialized
 109     cyg_uint32          syncmode;       // synchronization protocol
 110     char                *name;          // stack name
 111     char                *devname;       // hardware device name
 112     CYG_ADDRWORD        data;           // private data value
 113
 114     int     (*init)( cyg_nstab_entry *nste );
 115     int     (*socket)( cyg_nstab_entry *nste, int domain, int type,
 116                        int protocol, cyg_file *file );
 117 };</PRE
 118 ></TD
 119 ></TR
 120 ></TABLE
 121 ><P
 122 >This table is analogous to a combination of the filesystem and mount
 123 tables.</P
 124 ><P
 125 >The <TT
 126 CLASS="STRUCTFIELD"
 127 ><I
 128 >valid</I
 129 ></TT
 130 > field is set
 131 <TT
 132 CLASS="LITERAL"
 133 >true</TT
 134 > if the stack's <TT
 135 CLASS="FUNCTION"
 136 >init()</TT
 137 >
 138 function returned successfully and the
 139 <TT
 140 CLASS="STRUCTFIELD"
 141 ><I
 142 >syncmode</I
 143 ></TT
 144 > field contains the
 145 <TT
 146 CLASS="LITERAL"
 147 >CYG_SYNCMODE_SOCK_*</TT
 148 > bits described above.</P
 149 ><P
 150 >The <TT
 151 CLASS="STRUCTFIELD"
 152 ><I
 153 >name</I
 154 ></TT
 155 > field contains the name of the
 156 protocol stack.</P
 157 ><P
 158 >The <TT
 159 CLASS="STRUCTFIELD"
 160 ><I
 161 >devname</I
 162 ></TT
 163 > field names the device that the stack is using. This may
 164 reference a device under &quot;/dev&quot;, or may be a name that is only
 165 meaningful to the stack itself.</P
 166 ><P
 167 >The <TT
 168 CLASS="FUNCTION"
 169 >init()</TT
 170 > function pointer is called during
 171 system initialization to start the protocol stack running. If it
 172 returns non-zero the <TT
 173 CLASS="STRUCTFIELD"
 174 ><I
 175 >valid</I
 176 ></TT
 177 > field is set
 178 false and the stack will be ignored subsequently.</P
 179 ><P
 180 >The <TT
 181 CLASS="FUNCTION"
 182 >socket()</TT
 183 > function is called to attempt to create a socket in the
 184 stack. When the <TT
 185 CLASS="FUNCTION"
 186 >socket()</TT
 187 > API function is called the netstack table is
 188 scanned and for each valid entry the <TT
 189 CLASS="FUNCTION"
 190 >socket()</TT
 191 >
 192 function pointer is called. If
 193 this returns non-zero then the scan continues to the next valid stack,
 194 or terminates with an error if the end of the table is reached.</P
 195 ><P
 196 >The result of a successful socket call is an initialized file object
 197 with the <TT
 198 CLASS="STRUCTFIELD"
 199 ><I
 200 >f_xops</I
 201 ></TT
 202 > field pointing to the
 203 following structure:</P
 204 ><TABLE
 205 BORDER="5"
 206 BGCOLOR="#E0E0F0"
 207 WIDTH="70%"
 208 ><TR
 209 ><TD
 210 ><PRE
 211 CLASS="PROGRAMLISTING"
 212 >struct cyg_sock_ops
 213 {
 214     int (*bind)      ( cyg_file *fp, const sockaddr *sa, socklen_t len );
 215     int (*connect)   ( cyg_file *fp, const sockaddr *sa, socklen_t len );
 216     int (*accept)    ( cyg_file *fp, cyg_file *new_fp,
 217                        struct sockaddr *name, socklen_t *anamelen );
 218     int (*listen)    ( cyg_file *fp, int len );
 219     int (*getname)   ( cyg_file *fp, sockaddr *sa, socklen_t *len, int peer );
 220     int (*shutdown)  ( cyg_file *fp, int flags );
 221     int (*getsockopt)( cyg_file *fp, int level, int optname,
 222                        void *optval, socklen_t *optlen);
 223     int (*setsockopt)( cyg_file *fp, int level, int optname,
 224                        const void *optval, socklen_t optlen);
 225     int (*sendmsg)   ( cyg_file *fp, const struct msghdr *m,
 226                        int flags, ssize_t *retsize );
 227     int (*recvmsg)   ( cyg_file *fp, struct msghdr *m,
 228                        socklen_t *namelen, ssize_t *retsize );
 229 };</PRE
 230 ></TD
 231 ></TR
 232 ></TABLE
 233 ><P
 234 >It should be obvious from the names of these functions which API calls
 235 they provide support for. The <TT
 236 CLASS="FUNCTION"
 237 >getname()</TT
 238 > function
 239 pointer provides support for both <TT
 240 CLASS="FUNCTION"
 241 >getsockname()</TT
 242 >
 243 and <TT
 244 CLASS="FUNCTION"
 245 >getpeername()</TT
 246 > while the
 247 <TT
 248 CLASS="FUNCTION"
 249 >sendmsg()</TT
 250 > and <TT
 251 CLASS="FUNCTION"
 252 >recvmsg()</TT
 253 >
 254 function pointers provide support for <TT
 255 CLASS="FUNCTION"
 256 >send()</TT
 257 >,
 258 <TT
 259 CLASS="FUNCTION"
 260 >sendto()</TT
 261 >, <TT
 262 CLASS="FUNCTION"
 263 >sendmsg()</TT
 264 >,
 265 <TT
 266 CLASS="FUNCTION"
 267 >recv()</TT
 268 >, <TT
 269 CLASS="FUNCTION"
 270 >recvfrom()</TT
 271 > and
 272 <TT
 273 CLASS="FUNCTION"
 274 >recvmsg()</TT
 275 > as appropriate.</P
 276 ></DIV
 277 ><DIV
 278 CLASS="NAVFOOTER"
 279 ><HR
 280 ALIGN="LEFT"
 281 WIDTH="100%"><TABLE
 282 SUMMARY="Footer navigation table"
 283 WIDTH="100%"
 284 BORDER="0"
 285 CELLPADDING="0"
 286 CELLSPACING="0"
 287 ><TR
 288 ><TD
 289 WIDTH="33%"
 290 ALIGN="left"
 291 VALIGN="top"
 292 ><A
 293 HREF="fileio-mounting.html"
 294 ACCESSKEY="P"
 295 >Prev</A
 296 ></TD
 297 ><TD
 298 WIDTH="34%"
 299 ALIGN="center"
 300 VALIGN="top"
 301 ><A
 302 HREF="ecos-ref.html"
 303 ACCESSKEY="H"
 304 >Home</A
 305 ></TD
 306 ><TD
 307 WIDTH="33%"
 308 ALIGN="right"
 309 VALIGN="top"
 310 ><A
 311 HREF="fileio-select.html"
 312 ACCESSKEY="N"
 313 >Next</A
 314 ></TD
 315 ></TR
 316 ><TR
 317 ><TD
 318 WIDTH="33%"
 319 ALIGN="left"
 320 VALIGN="top"
 321 >Initialization and Mounting</TD
 322 ><TD
 323 WIDTH="34%"
 324 ALIGN="center"
 325 VALIGN="top"
 326 ><A
 327 HREF="fileio.html"
 328 ACCESSKEY="U"
 329 >Up</A
 330 ></TD
 331 ><TD
 332 WIDTH="33%"
 333 ALIGN="right"
 334 VALIGN="top"
 335 >Select</TD
 336 ></TR
 337 ></TABLE
 338 ></DIV
 339 ></BODY
 340 ></HTML
 341 >