Главная Обзор Помощь
Регистрация Вход
third
/
srs
зеркало из https://github.com/ossrs/srs
2
0
Ответвить 0
Файлы
Дерево: e801174ab2
Ветки Метки
srs
/
trunk
/
3rdparty
/
st-srs
/
docs
/
reference.html

reference.html 99 KB
История Исходник

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120 
  1. <HTML>
    2. 

  2. <HEAD>
    3. 

  3. <TITLE>State Threads Library Reference</TITLE>
    4. 

  4. </HEAD>
    5. 

  5. <BODY BGCOLOR=#FFFFFF>
    6. 

  6. 

  7. <H2>State Threads Library Reference</H2>
    8. 

  8. 

  9. <DL>
    10. 

  10. <DD><A HREF=#types><B>Types</B></A></DD>
    11. 

  11. <DL><DD><A HREF=#thread_t>st_thread_t</A></DD></DL>
    12. 

  12. <DL><DD><A HREF=#cond_t>st_cond_t</A></DD></DL>
    13. 

  13. <DL><DD><A HREF=#mutex_t>st_mutex_t</A></DD></DL>
    14. 

  14. <DL><DD><A HREF=#utime_t>st_utime_t</A></DD></DL>
    15. 

  15. <DL><DD><A HREF=#netfd_t>st_netfd_t</A></DD></DL>
    16. 

  16. <DL><DD><A HREF=#switch_cb_t>st_switch_cb_t</A></DD></DL>
    17. 

  17. <P>
    18. 

  18. <DD><A HREF=#errors><B>Error Handling</B></A></DD>
    19. 

  19. <P>
    20. 

  20. <DD><A HREF=#init><B>Library Initialization</B></A></DD>
    21. 

  21. <P>
    22. 

  22. <DL><DD><A HREF=#st_init>st_init()</A></DD></DL>
    23. 

  23. <DL><DD><A HREF=#getfdlimit>st_getfdlimit()</A></DD></DL>
    24. 

  24. <DL><DD><A HREF=#set_eventsys>st_set_eventsys()</A></DD></DL>
    25. 

  25. <DL><DD><A HREF=#get_eventsys>st_get_eventsys()</A></DD></DL>
    26. 

  26. <DL><DD><A HREF=#get_eventsys_name>st_get_eventsys_name()</A></DD></DL>
    27. 

  27. <DL><DD><A HREF=#set_utime_function>st_set_utime_function()</A></DD></DL>
    28. 

  28. <DL><DD><A HREF=#timecache_set>st_timecache_set()</A></DD></DL>
    29. 

  29. <DL><DD><A HREF=#randomize_stacks>st_randomize_stacks()</A></DD></DL>
    30. 

  30. <P>
    31. 

  31. <DL><DD><A HREF=#switch_cb_t><B>st_switch_cb_t</B> type</A></DD></DL>
    32. 

  32. <DL><DD><A HREF=#set_switch_in_cb>st_set_switch_in_cb()</A></DD></DL>
    33. 

  33. <DL><DD><A HREF=#set_switch_out_cb>st_set_switch_out_cb()</A></DD></DL>
    34. 

  34. <P>
    35. 

  35. <DD><A HREF=#threads><B>Thread Control and Identification</B></A></DD>
    36. 

  36. <P>
    37. 

  37. <DL><DD><A HREF=#thread_t><B>st_thread_t</B> type</A></DD></DL>
    38. 

  38. <DL><DD><A HREF=#thread_create>st_thread_create()</A></DD></DL>
    39. 

  39. <DL><DD><A HREF=#thread_exit>st_thread_exit()</A></DD></DL>
    40. 

  40. <DL><DD><A HREF=#thread_join>st_thread_join()</A></DD></DL>
    41. 

  41. <DL><DD><A HREF=#thread_self>st_thread_self()</A></DD></DL>
    42. 

  42. <DL><DD><A HREF=#thread_interrupt>st_thread_interrupt()</A></DD></DL>
    43. 

  43. <DL><DD><A HREF=#sleep>st_sleep()</A></DD></DL>
    44. 

  44. <DL><DD><A HREF=#sleep>st_usleep()</A></DD></DL>
    45. 

  45. <DL><DD><A HREF=#randomize_stacks>st_randomize_stacks()</A></DD></DL>
    46. 

  46. <P>
    47. 

  47. <DD><A HREF=#priv><B>Per-Thread Private Data</B></A></DD>
    48. 

  48. <P>
    49. 

  49. <DL><DD><A HREF=#key_create>st_key_create()</A></DD></DL>
    50. 

  50. <DL><DD><A HREF=#key_getlimit>st_key_getlimit()</A></DD></DL>
    51. 

  51. <DL><DD><A HREF=#thread_setspecific>st_thread_setspecific()</A></DD></DL>
    52. 

  52. <DL><DD><A HREF=#thread_getspecific>st_thread_getspecific()</A></DD></DL>
    53. 

  53. <P>
    54. 

  54. <DD><A HREF=#sync><B>Synchronization</B></A></DD>
    55. 

  55. <P>
    56. 

  56. <DL><DD><A HREF=#cond_t><B>st_cond_t</B> type</A></DD></DL>
    57. 

  57. <DL><DD><A HREF=#cond_new>st_cond_new()</A></DD></DL>
    58. 

  58. <DL><DD><A HREF=#cond_destroy>st_cond_destroy()</A></DD></DL>
    59. 

  59. <DL><DD><A HREF=#cond_wait>st_cond_wait()</A></DD></DL>
    60. 

  60. <DL><DD><A HREF=#cond_timedwait>st_cond_timedwait()</A></DD></DL>
    61. 

  61. <DL><DD><A HREF=#cond_signal>st_cond_signal()</A></DD></DL>
    62. 

  62. <DL><DD><A HREF=#cond_broadcast>st_cond_broadcast()</A></DD></DL>
    63. 

  63. <P>
    64. 

  64. <DL><DD><A HREF=#mutex_t><B>st_mutex_t</B> type</A></DD></DL>
    65. 

  65. <DL><DD><A HREF=#mutex_new>st_mutex_new()</A></DD></DL>
    66. 

  66. <DL><DD><A HREF=#mutex_destroy>st_mutex_destroy()</A></DD></DL>
    67. 

  67. <DL><DD><A HREF=#mutex_lock>st_mutex_lock()</A></DD></DL>
    68. 

  68. <DL><DD><A HREF=#mutex_trylock>st_mutex_trylock()</A></DD></DL>
    69. 

  69. <DL><DD><A HREF=#mutex_unlock>st_mutex_unlock()</A></DD></DL>
    70. 

  70. <P>
    71. 

  71. <DD><A HREF=#timing><B>Timing</B></A></DD>
    72. 

  72. <P>
    73. 

  73. <DL><DD><A HREF=#utime_t><B>st_utime_t</B> type</A></DD></DL>
    74. 

  74. <DL><DD><A HREF=#utime>st_utime()</A></DD></DL>
    75. 

  75. <DL><DD><A HREF=#set_utime_function>st_set_utime_function()</A></DD></DL>
    76. 

  76. <DL><DD><A HREF=#timecache_set>st_timecache_set()</A></DD></DL>
    77. 

  77. <DL><DD><A HREF=#time>st_time()</A></DD></DL>
    78. 

  78. <P>
    79. 

  79. <DD><A HREF=#io><B>I/O Functions</B></A></DD>
    80. 

  80. <P>
    81. 

  81. <DL><DD><A HREF=#netfd_t><B>st_netfd_t</B> type</A></DD></DL>
    82. 

  82. <DL><DD><A HREF=#netfd_open>st_netfd_open()</A></DD></DL>
    83. 

  83. <DL><DD><A HREF=#netfd_open_socket>st_netfd_open_socket()</A></DD></DL>
    84. 

  84. <DL><DD><A HREF=#netfd_free>st_netfd_free()</A></DD></DL>
    85. 

  85. <DL><DD><A HREF=#netfd_close>st_netfd_close()</A></DD></DL>
    86. 

  86. <DL><DD><A HREF=#netfd_fileno>st_netfd_fileno()</A></DD></DL>
    87. 

  87. <DL><DD><A HREF=#netfd_setspecific>st_netfd_setspecific()</A></DD></DL>
    88. 

  88. <DL><DD><A HREF=#netfd_getspecific>st_netfd_getspecific()</A></DD></DL>
    89. 

  89. <DL><DD><A HREF=#netfd_serialize_accept>st_netfd_serialize_accept()</A></DD>
    90. 

  90. </DL>
    91. 

  91. <DL><DD><A HREF=#netfd_poll>st_netfd_poll()</A></DD></DL>
    92. 

  92. <P>
    93. 

  93. <DL><DD><A HREF=#accept>st_accept()</A></DD></DL>
    94. 

  94. <DL><DD><A HREF=#connect>st_connect()</A></DD></DL>
    95. 

  95. <DL><DD><A HREF=#read>st_read()</A></DD></DL>
    96. 

  96. <DL><DD><A HREF=#read_fully>st_read_fully()</A></DD></DL>
    97. 

  97. <DL><DD><A HREF=#read_resid>st_read_resid()</A></DD></DL>
    98. 

  98. <DL><DD><A HREF=#readv>st_readv()</A></DD></DL>
    99. 

  99. <DL><DD><A HREF=#readv_resid>st_readv_resid()</A></DD></DL>
    100. 

  100. <DL><DD><A HREF=#write>st_write()</A></DD></DL>
    101. 

  101. <DL><DD><A HREF=#write_resid>st_write_resid()</A></DD></DL>
    102. 

  102. <DL><DD><A HREF=#writev>st_writev()</A></DD></DL>
    103. 

  103. <DL><DD><A HREF=#writev_resid>st_writev_resid()</A></DD></DL>
    104. 

  104. <DL><DD><A HREF=#recvfrom>st_recvfrom()</A></DD></DL>
    105. 

  105. <DL><DD><A HREF=#sendto>st_sendto()</A></DD></DL>
    106. 

  106. <DL><DD><A HREF=#recvmsg>st_recvmsg()</A></DD></DL>
    107. 

  107. <DL><DD><A HREF=#sendmsg>st_sendmsg()</A></DD></DL>
    108. 

  108. <P>
    109. 

  109. <DL><DD><A HREF=#open>st_open()</A></DD></DL>
    110. 

  110. <DL><DD><A HREF=#poll>st_poll()</A></DD></DL>
    111. 

  111. <P>
    112. 

  112. <DD><A HREF=#progr><B>Program Structure</B></A></DD>
    113. 

  113. <P>
    114. 

  114. <DD><A HREF=#block><B>List of Blocking Functions</B></A></DD>
    115. 

  115. <P>
    116. 

  116. </DL>
    117. 

  117. <P>
    118. 

  118. <HR>
    119. 

  119. <P>
    120. 

  120. 

  121. 

  122. <A NAME="types">
    123. 

  123. <H2>Types</H2>
    124. 

  124. </A>
    125. 

  125. The State Thread library defines the following types in the <TT>st.h</TT>
    126. 

  126. header file:
    127. 

  127. <P>
    128. 

  128. <DL>
    129. 

  129. <DD><A HREF=#thread_t>st_thread_t</A></DD>
    130. 

  130. <DD><A HREF=#cond_t>st_cond_t</A></DD>
    131. 

  131. <DD><A HREF=#mutex_t>st_mutex_t</A></DD>
    132. 

  132. <DD><A HREF=#utime_t>st_utime_t</A></DD>
    133. 

  133. <DD><A HREF=#netfd_t>st_netfd_t</A></DD>
    134. 

  134. </DL>
    135. 

  135. <P>
    136. 

  136. <HR>
    137. 

  137. <P>
    138. 

  138. 

  139. <A NAME="thread_t">
    140. 

  140. <H4>st_thread_t</H4>
    141. 

  141. </A>
    142. 

  142. Thread type.
    143. 

  143. <P>
    144. 

  144. <H5>Syntax</H5>
    145. 

  145. 

  146. <PRE>
    147. 

  147. #include &lt;st.h&gt;
    148. 

  148. 

  149. typedef void *  st_thread_t;
    150. 

  150. </PRE>
    151. 

  151. <P>
    152. 

  152. <H5>Description</H5>
    153. 

  153. 

  154. A thread is represented and identified by a pointer to an opaque data
    155. 

  155. structure. This pointer is a required parameter for most of the functions
    156. 

  156. that operate on threads.
    157. 

  157. <P>
    158. 

  158. The thread identifier remains valid until the thread returns from its root
    159. 

  159. function and, if the thread was created joinable, is joined.
    160. 

  160. <P>
    161. 

  161. <HR>
    162. 

  162. <P>
    163. 

  163. 

  164. <A NAME="cond_t">
    165. 

  165. <H4>st_cond_t</H4>
    166. 

  166. </A>
    167. 

  167. Condition variable type.
    168. 

  168. <P>
    169. 

  169. <H5>Syntax</H5>
    170. 

  170. 

  171. <PRE>
    172. 

  172. #include &lt;st.h&gt;
    173. 

  173. 

  174. typedef void *  st_cond_t;
    175. 

  175. </PRE>
    176. 

  176. <P>
    177. 

  177. <H5>Description</H5>
    178. 

  178. 

  179. A condition variable is an opaque object identified by a pointer.
    180. 

  180. Condition variables provide synchronization primitives to wait for or wake
    181. 

  181. up threads waiting for certain conditions to be satisfied.
    182. 

  182. <P>
    183. 

  183. In the State Threads library there is no need to lock a mutex before
    184. 

  184. waiting on a condition variable.
    185. 

  185. <P>
    186. 

  186. <HR>
    187. 

  187. <P>
    188. 

  188. 

  189. <A NAME="mutex_t">
    190. 

  190. <H4>st_mutex_t</H4>
    191. 

  191. </A>
    192. 

  192. Mutex type.
    193. 

  193. <P>
    194. 

  194. <H5>Syntax</H5>
    195. 

  195. 

  196. <PRE>
    197. 

  197. #include &lt;st.h&gt;
    198. 

  198. 

  199. typedef void *  st_mutex_t;
    200. 

  200. </PRE>
    201. 

  201. <P>
    202. 

  202. <H5>Description</H5>
    203. 

  203. 

  204. A mutex is an opaque object identified by a pointer.
    205. 

  205. Mutual exclusion locks (mutexes) are used to serialize the execution of
    206. 

  206. threads through critical sections of code.
    207. 

  207. <P>
    208. 

  208. If application using the State Threads library is written with no
    209. 

  209. I/O or control yielding in critical sections (that is no
    210. 

  210. <A HREF=#block>blocking functions</A> in critical sections), then there is
    211. 

  211. no need for mutexes.<P>
    212. 

  212. These mutexes can only be used for intra-process thread synchronization.
    213. 

  213. They cannot be used for inter-process synchronization.
    214. 

  214. <P>
    215. 

  215. <HR>
    216. 

  216. <P>
    217. 

  217. 

  218. <A NAME="utime_t">
    219. 

  219. <H4>st_utime_t</H4>
    220. 

  220. </A>
    221. 

  221. High resolution time type ("u" stands for "micro").
    222. 

  222. <P>
    223. 

  223. <H5>Syntax</H5>
    224. 

  224. 

  225. <PRE>
    226. 

  226. #include &lt;st.h&gt;
    227. 

  227. 

  228. typedef unsigned long long  st_utime_t;
    229. 

  229. </PRE>
    230. 

  230. <P>
    231. 

  231. <H5>Description</H5>
    232. 

  232. 

  233. This datatype (unsigned 64-bit integer) represents high-resolution real time
    234. 

  234. expressed in microseconds since some arbitrary time in the past. It is not
    235. 

  235. correlated in any way to the time of day.
    236. 

  236. <P>
    237. 

  237. <HR>
    238. 

  238. <P>
    239. 

  239. 

  240. <A NAME="netfd_t">
    241. 

  241. <H4>st_netfd_t</H4>
    242. 

  242. </A>
    243. 

  243. File descriptor type.
    244. 

  244. <P>
    245. 

  245. <H5>Syntax</H5>
    246. 

  246. 

  247. <PRE>
    248. 

  248. #include &lt;st.h&gt;
    249. 

  249. 

  250. typedef void *  st_netfd_t;
    251. 

  251. </PRE>
    252. 

  252. <P>
    253. 

  253. <H5>Description</H5>
    254. 

  254. 

  255. This datatype typically represents any open end point of network
    256. 

  256. communication (socket, end point of a pipe, FIFO, etc.) but can
    257. 

  257. encapsulate any open file descriptor.  Objects of this type are
    258. 

  258. identified by a pointer to an opaque data structure.
    259. 

  259. 

  260. <P>
    261. 

  261. <HR>
    262. 

  262. <P>
    263. 

  263. 

  264. <A NAME="switch_cb_t">
    265. 

  265. <H4>st_switch_cb_t</H4>
    266. 

  266. </A>
    267. 

  267. Context switch callback function type.
    268. 

  268. <P>
    269. 

  269. <H5>Syntax</H5>
    270. 

  270. 

  271. <PRE>
    272. 

  272. #include &lt;st.h&gt;
    273. 

  273. 

  274. typedef void (*st_switch_cb_t)(void);
    275. 

  275. </PRE>
    276. 

  276. <P>
    277. 

  277. <H5>Description</H5>
    278. 

  278. 

  279. This datatype is a convenience type for describing a pointer
    280. 

  280. to a function that will be called when a thread is set to stop
    281. 

  281. or set to run.
    282. 

  282. This feature is available only when <TT>ST_SWITCH_CB</TT> is defined
    283. 

  283. in <TT>&lt;st.h&gt;</TT>.
    284. 

  284. 

  285. <P>
    286. 

  286. <HR>
    287. 

  287. <P>
    288. 

  288. 

  289. <A NAME="errors">
    290. 

  290. <H2>Error Handling</H2>
    291. 

  291. </A>
    292. 

  292. 

  293. All State Threads library non-void functions return on success either a
    294. 

  294. non-negative integer or a pointer to a newly created object (constructor-type
    295. 

  295. functions). On failure they return either <TT>-1</TT> or a <TT>NULL</TT>
    296. 

  296. pointer respectively and set global <TT>errno</TT> to indicate the error.
    297. 

  297. It is safe to use <TT>errno</TT> because it is set right before the function
    298. 

  298. return and only one thread at a time can modify its value.<P>
    299. 

  299. The <TT>perror(3)</TT> function can be used to produce an error message on the
    300. 

  300. standard error output.
    301. 

  301. <P>
    302. 

  302. <HR>
    303. 

  303. <P>
    304. 

  304. 

  305. <A NAME="init">
    306. 

  306. <H2>Library Initialization</H2>
    307. 

  307. </A>
    308. 

  308. <P>
    309. 

  309. <DL>
    310. 

  310. <DD><A HREF=#st_init>st_init()</A></DD>
    311. 

  311. <DD><A HREF=#getfdlimit>st_getfdlimit()</A></DD>
    312. 

  312. <DD><A HREF=#set_eventsys>st_set_eventsys()</A></DD>
    313. 

  313. <DD><A HREF=#get_eventsys>st_get_eventsys()</A></DD>
    314. 

  314. <DD><A HREF=#get_eventsys_name>st_get_eventsys_name()</A></DD>
    315. 

  315. <P>
    316. 

  316. These functions operate on a callback function of type
    317. 

  317. <A HREF=#switch_cb_t><B>st_switch_cb_t</B></A>:
    318. 

  318. <DD><A HREF=#set_switch_in_cb>st_set_switch_in_cb()</A></DD>
    319. 

  319. <DD><A HREF=#set_switch_out_cb>st_set_switch_out_cb()</A></DD>
    320. 

  320. </DL>
    321. 

  321. <P>
    322. 

  322. <HR>
    323. 

  323. <P>
    324. 

  324. 

  325. <A NAME="st_init">
    326. 

  326. <H4>st_init()</H4>
    327. 

  327. </A>
    328. 

  328. Initializes the runtime.
    329. 

  329. <P>
    330. 

  330. <H5>Syntax</H5>
    331. 

  331. 

  332. <PRE>
    333. 

  333. #include &lt;st.h&gt;
    334. 

  334. 

  335. int st_init(void);
    336. 

  336. </PRE>
    337. 

  337. <P>
    338. 

  338. <H5>Parameters</H5>
    339. 

  339. None.
    340. 

  340. <P>
    341. 

  341. <H5>Returns</H5>
    342. 

  342. Upon successful completion, a value of <TT>0</TT> is returned.
    343. 

  343. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    344. 

  344. to indicate the error.
    345. 

  345. <P>
    346. 

  346. <H5>Description</H5>
    347. 

  347. This function initializes the library runtime. It should be called near
    348. 

  348. the beginning of the application's <TT>main()</TT> function before any other
    349. 

  349. State Threads library function is called.<P>
    350. 

  350. Among other things, this function limits the number of open file descriptors
    351. 

  351. to the OS imposed per-process maximum number or, if <TT>select(2)</TT> is
    352. 

  352. used, to <TT>FD_SETSIZE</TT>, whichever is less (<TT>getrlimit(2)</TT>).
    353. 

  353. This limit can be
    354. 

  354. retrieved by <A HREF=#getfdlimit>st_getfdlimit()</A>. It also sets the
    355. 

  355. disposition of the <TT>SIGPIPE</TT> signal to <TT>SIG_IGN</TT> (to be ignored)
    356. 

  356. (<TT>signal(5)</TT>).
    357. 

  357. <P>
    358. 

  358. Unlike POSIX threads, a new process created by the <TT>fork(2)</TT> system
    359. 

  359. call is an <I>exact</I> copy of the calling process and all state threads
    360. 

  360. which are running in the parent do exist in the child. That means that
    361. 

  361. <TT>st_init()</TT> may be called either before or after multiple processes
    362. 

  362. are created by <TT>fork(2)</TT>.
    363. 

  363. <P>
    364. 

  364. If the library runtime is not properly initialized (e.g., <TT>st_init()</TT>
    365. 

  365. is accidentally omitted), then the process will receive either an arithmetic
    366. 

  366. exception (SIGFPE or SIGTRAP) or segmentation fault (SIGSEGV) signal upon
    367. 

  367. new thread creation or the first context switch, respectively.
    368. 

  368. <P>
    369. 

  369. <HR>
    370. 

  370. <P>
    371. 

  371. <A NAME="getfdlimit">
    372. 

  372. <H4>st_getfdlimit()</H4>
    373. 

  373. </A>
    374. 

  374. Returns the maximum number of file descriptors that the calling process
    375. 

  375. can open.
    376. 

  376. <P>
    377. 

  377. <H5>Syntax</H5>
    378. 

  378. 

  379. <PRE>
    380. 

  380. #include &lt;st.h&gt;
    381. 

  381. 

  382. int st_getfdlimit(void);
    383. 

  383. </PRE>
    384. 

  384. <P>
    385. 

  385. <H5>Parameters</H5>
    386. 

  386. None.
    387. 

  387. <P>
    388. 

  388. <H5>Returns</H5>
    389. 

  389. The maximum number of file descriptors that the calling process can open.
    390. 

  390. If this function is called before the library is successfully initialized by
    391. 

  391. <A HREF=#st_init>st_init()</A>, a value of <TT>-1</TT> is returned.
    392. 

  392. <P>
    393. 

  393. <H5>Description</H5>
    394. 

  394. This function returns the limit on the number of open file descriptors which
    395. 

  395. is set by the <A HREF=#st_init>st_init()</A> function.
    396. 

  396. <P>
    397. 

  397. <HR>
    398. 

  398. <P>
    399. 

  399. 

  400. <A NAME="set_eventsys">
    401. 

  401. <H4>st_set_eventsys()</H4>
    402. 

  402. </A>
    403. 

  403. Sets event notification mechanism.
    404. 

  404. <P>
    405. 

  405. <H5>Syntax</H5>
    406. 

  406. 

  407. <PRE>
    408. 

  408. #include &lt;st.h&gt;
    409. 

  409. 

  410. int st_set_eventsys(int eventsys);
    411. 

  411. </PRE>
    412. 

  412. <P>
    413. 

  413. <H5>Parameters</H5>
    414. 

  414. <TT>st_set_eventsys()</TT> has the following parameter:<P>
    415. 

  415. <TT>eventsys</TT><P>
    416. 

  416. An integer value identifying selected event notification mechanism. The
    417. 

  417. following values are defined in the <TT>st.h</TT> header file:
    418. 

  418. <P>
    419. 

  419. <TABLE BORDER=0 CELLPADDING=5 CELLSPACING=15>
    420. 

  420. <TR>
    421. 

  421. <TD VALIGN=TOP><TT>ST_EVENTSYS_DEFAULT</TT></TD>
    422. 

  422. <TD>Use default event notification mechanism. Usually it's <TT>select(2)</TT>
    423. 

  423. but if the library was compiled with the <TT>USE_POLL</TT> macro defined
    424. 

  424. then the default is <TT>poll(2)</TT>.</TD>
    425. 

  425. </TR>
    426. 

  426. <TR>
    427. 

  427. <TD VALIGN=TOP><TT>ST_EVENTSYS_SELECT</TT></TD>
    428. 

  428. <TD>Use <TT>select(2)</TT> as an event notification mechanism.</TD>
    429. 

  429. </TR>
    430. 

  430. <TD VALIGN=TOP><TT>ST_EVENTSYS_POLL</TT></TD>
    431. 

  431. <TD>Use <TT>poll(2)</TT> as an event notification mechanism.</TD>
    432. 

  432. </TR>
    433. 

  433. <TD VALIGN=TOP><TT>ST_EVENTSYS_ALT</TT></TD>
    434. 

  434. <TD>Use an alternative event notification mechanism. The actual
    435. 

  435. mechanism selected depends on OS support. For example, <TT>epoll(4)</TT>
    436. 

  436. will be used on Linux if supported and <TT>kqueue(2)</TT> will be used
    437. 

  437. on FreeBSD/OpenBSD. If the OS supports no alternative event
    438. 

  438. notification mechanism, setting <TT>ST_EVENTSYS_ALT</TT> has no effect
    439. 

  439. and the <TT>ST_EVENTSYS_DEFAULT</TT> mechanism will be used.</TD>
    440. 

  440. </TR>
    441. 

  441. </TABLE>
    442. 

  442. <P>
    443. 

  443. <H5>Returns</H5>
    444. 

  444. Upon successful completion, a value of <TT>0</TT> is returned.
    445. 

  445. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    446. 

  446. to indicate the error:<P>
    447. 

  447. <TABLE BORDER=0 CELLSPACING=15>
    448. 

  448. <TR><TD><TT>EINVAL</TT></TD>
    449. 

  449. <TD>
    450. 

  450. The supplied <TT>eventsys</TT> parameter has an invalid value.
    451. 

  451. </TD></TR>
    452. 

  452. <TR><TD><TT>EBUSY</TT></TD>
    453. 

  453. <TD>
    454. 

  454. The event notification mechanism has already been set.
    455. 

  455. </TD></TR>
    456. 

  456. </TABLE>
    457. 

  457. <P>
    458. 

  458. <H5>Description</H5>
    459. 

  459. This function sets the event notification mechanism that will be used by
    460. 

  460. the State Threads library. To have any effect, it must be called
    461. 

  461. <i>before</i> the <A HREF=#st_init>st_init()</A> function which performs
    462. 

  462. the actual initialization. If <TT>st_set_eventsys()</TT> is not called,
    463. 

  463. <A HREF=#st_init>st_init()</A> will set the <TT>ST_EVENTSYS_DEFAULT</TT>
    464. 

  464. mechanism. The mechanism cannot be changed once set.
    465. 

  465. <P>
    466. 

  466. There are no strict rules for selecting an event notification
    467. 

  467. mechanism.  The "best" one depends on how your application behaves.
    468. 

  468. Try a few to see which one works best for you.  As a rule of
    469. 

  469. thumb, you should use the <TT>ST_EVENTSYS_ALT</TT> mechanism if your
    470. 

  470. application deals with a very large number of network connections of
    471. 

  471. which only a few are active at once.
    472. 

  472. <P>
    473. 

  473. <HR>
    474. 

  474. <P>
    475. 

  475. <A NAME="get_eventsys">
    476. 

  476. <H4>st_get_eventsys()</H4>
    477. 

  477. </A>
    478. 

  478. Returns the integer value identifying the event notification mechanism
    479. 

  479. being used by the State Threads library.
    480. 

  480. <P>
    481. 

  481. <H5>Syntax</H5>
    482. 

  482. 

  483. <PRE>
    484. 

  484. #include &lt;st.h&gt;
    485. 

  485. 

  486. int st_get_eventsys(void);
    487. 

  487. </PRE>
    488. 

  488. <P>
    489. 

  489. <H5>Parameters</H5>
    490. 

  490. None.
    491. 

  491. <P>
    492. 

  492. <H5>Returns</H5>
    493. 

  493. The integer value identifying the current event notification mechanism.
    494. 

  494. This value can be one of the following (see <A
    495. 

  495. HREF=#set_eventsys>st_set_eventsys()</A>):
    496. 

  496. <TT>ST_EVENTSYS_SELECT</TT>, <TT>ST_EVENTSYS_POLL</TT>, or
    497. 

  497. <TT>ST_EVENTSYS_ALT</TT>. Future versions of the library may return other
    498. 

  498. values. If a mechanism hasn't been set yet, a value of <TT>-1</TT> is returned.
    499. 

  499. <P>
    500. 

  500. <H5>Description</H5>
    501. 

  501. This function returns the integer value identifying the event notification
    502. 

  502. mechanism which is actually being used by the State Threads library.
    503. 

  503. <P>
    504. 

  504. <HR>
    505. 

  505. <P>
    506. 

  506. <A NAME="get_eventsys_name">
    507. 

  507. <H4>st_get_eventsys_name()</H4>
    508. 

  508. </A>
    509. 

  509. Returns the name of the event notification mechanism being used by the
    510. 

  510. State Threads library.
    511. 

  511. <P>
    512. 

  512. <H5>Syntax</H5>
    513. 

  513. 

  514. <PRE>
    515. 

  515. #include &lt;st.h&gt;
    516. 

  516. 

  517. const char *st_get_eventsys_name(void);
    518. 

  518. </PRE>
    519. 

  519. <P>
    520. 

  520. <H5>Parameters</H5>
    521. 

  521. None.
    522. 

  522. <P>
    523. 

  523. <H5>Returns</H5>
    524. 

  524. The string identifying the current event notification mechanism. If a
    525. 

  525. mechanism hasn't been set yet (see <A
    526. 

  526. HREF=#set_eventsys>st_set_eventsys()</A>), an empty string is
    527. 

  527. returned. Possible return values are <TT>"select"</TT>,
    528. 

  528. <TT>"poll"</TT>, <TT>"kqueue"</TT>, or <TT>"epoll"</TT>.  Future versions
    529. 

  529. of the library may return other values.
    530. 

  530. <P>
    531. 

  531. <H5>Description</H5>
    532. 

  532. This function returns the string identifying the event notification
    533. 

  533. mechanism which is actually being used by the State Threads library.
    534. 

  534. <P>
    535. 

  535. <HR>
    536. 

  536. <P>
    537. 

  537. 

  538. <A NAME="set_switch_in_cb">
    539. 

  539. <H4>st_set_switch_in_cb()</H4>
    540. 

  540. </A>
    541. 

  541. <A NAME="set_switch_out_cb">
    542. 

  542. <H4>st_set_switch_out_cb()</H4>
    543. 

  543. </A>
    544. 

  544. Set the optional callback function for thread switches.
    545. 

  545. <P>
    546. 

  546. <H5>Syntax</H5>
    547. 

  547. 

  548. <PRE>
    549. 

  549. #include &lt;st.h&gt;
    550. 

  550. 

  551. st_switch_cb_t st_set_switch_in_cb(st_switch_cb_t cb);
    552. 

  552. st_switch_cb_t st_set_switch_out_cb(st_switch_cb_t cb);
    553. 

  553. </PRE>
    554. 

  554. <P>
    555. 

  555. <H5>Parameters</H5>
    556. 

  556. <TT>st_set_switch_in_cb()</TT> and <TT>st_set_switch_out_cb()</TT> have the
    557. 

  557. following parameter:<P>
    558. 

  558. <TT>cb</TT><P>
    559. 

  559. A function to be called when a thread is resumed and stopped respectively.<P>
    560. 

  560. <H5>Returns</H5>
    561. 

  561. The previous callback function pointer.
    562. 

  562. <P>
    563. 

  563. <H5>Description</H5>
    564. 

  564. These functions set the callback for when a thread is resumed and stopped
    565. 

  565. respectively.  After being called any thread switch will call the callback.
    566. 

  566. Use a <TT>NULL</TT> pointer to disable the callback (this is the default).
    567. 

  567. Use <A HREF=#thread_self>st_thread_self()</A> or <A HREF=#priv>thread
    568. 

  568. specific data</A> to differentiate between threads.<P>
    569. 

  569. These functions can be called at any time.<P>
    570. 

  570. This feature is available only when <TT>ST_SWITCH_CB</TT> is defined
    571. 

  571. in <TT>&lt;st.h&gt;</TT>.
    572. 

  572. <P>
    573. 

  573. <HR>
    574. 

  574. <P>
    575. 

  575. 

  576. <A NAME="threads">
    577. 

  577. <H2>Thread Control and Identification</H2>
    578. 

  578. </A>
    579. 

  579. <P>
    580. 

  580. These functions operate on a thread object of type
    581. 

  581. <A HREF=#thread_t><B>st_thread_t</B></A>.
    582. 

  582. <P>
    583. 

  583. <DL>
    584. 

  584. <DD><A HREF=#thread_create>st_thread_create()</A></DD>
    585. 

  585. <DD><A HREF=#thread_exit>st_thread_exit()</A></DD>
    586. 

  586. <DD><A HREF=#thread_join>st_thread_join()</A></DD>
    587. 

  587. <DD><A HREF=#thread_self>st_thread_self()</A></DD>
    588. 

  588. <DD><A HREF=#thread_interrupt>st_thread_interrupt()</A></DD>
    589. 

  589. <DD><A HREF=#sleep>st_sleep()</A></DD>
    590. 

  590. <DD><A HREF=#sleep>st_usleep()</A></DD>
    591. 

  591. <DD><A HREF=#randomize_stacks>st_randomize_stacks()</A></DD>
    592. 

  592. </DL>
    593. 

  593. <P>
    594. 

  594. <HR>
    595. 

  595. <P>
    596. 

  596. <A NAME="thread_create">
    597. 

  597. <H4>st_thread_create()</H4>
    598. 

  598. </A>
    599. 

  599. Creates a new thread.
    600. 

  600. <P>
    601. 

  601. <H5>Syntax</H5>
    602. 

  602. 

  603. <PRE>
    604. 

  604. #include &lt;st.h&gt;
    605. 

  605. 

  606. st_thread_t st_thread_create(void *(*start)(void *arg), void *arg,
    607. 

  607.                              int joinable, int stack_size);
    608. 

  608. 

  609. </PRE>
    610. 

  610. <P>
    611. 

  611. <H5>Parameters</H5>
    612. 

  612. <TT>st_thread_create()</TT> has the following parameters:<P>
    613. 

  613. <TT>start</TT><P>
    614. 

  614. A pointer to the thread's start function, which is called as the root of the
    615. 

  615. new thread. Return from this function terminates a thread.<P>
    616. 

  616. <TT>arg</TT><P>
    617. 

  617. A pointer to the root function's only parameter.<P>
    618. 

  618. <TT>joinable</TT><P>
    619. 

  619. Specifies whether the thread is joinable or unjoinable. If this parameter
    620. 

  620. is zero, the thread is unjoinable. Otherwise, it is joinable.
    621. 

  621. See also <A HREF=#thread_join>st_thread_join()</A>.<P>
    622. 

  622. <TT>stack_size</TT><P>
    623. 

  623. Specifies your preference for the size of the stack, in bytes, associated
    624. 

  624. with the newly created thread. If you pass zero in this parameter, the
    625. 

  625. default stack size will be used. The default stack size is 128 KB on IA-64
    626. 

  626. and 64 KB on all other platforms. On IA-64 only a half of <TT>stack_size</TT>
    627. 

  627. bytes is used for the memory stack. The other half is used for the register
    628. 

  628. stack backing store.
    629. 

  629. <P>
    630. 

  630. <H5>Returns</H5>
    631. 

  631. Upon successful completion, a new thread identifier is returned (this
    632. 

  632. identifier remains valid until the thread returns from its start function).
    633. 

  633. Otherwise, <TT>NULL</TT> is returned and <TT>errno</TT> is set
    634. 

  634. to indicate the error.
    635. 

  635. <P>
    636. 

  636. <H5>Description</H5>
    637. 

  637. This function creates a new thread. Note that the total number of threads
    638. 

  638. created by the application is limited by the amount of swap space available.
    639. 

  639. Upon thread creation, <TT>stack_size</TT> bytes are reserved on the swap
    640. 

  640. space. The stack pages are not actually used (valid) until touched by the
    641. 

  641. application.
    642. 

  642. <P>
    643. 

  643. <HR>
    644. 

  644. <P>
    645. 

  645. <A NAME="thread_exit">
    646. 

  646. <H4>st_thread_exit()</H4>
    647. 

  647. </A>
    648. 

  648. Terminates the calling thread.
    649. 

  649. <P>
    650. 

  650. <H5>Syntax</H5>
    651. 

  651. 

  652. <PRE>
    653. 

  653. #include &lt;st.h&gt;
    654. 

  654. 

  655. void st_thread_exit(void *retval);
    656. 

  656. </PRE>
    657. 

  657. <P>
    658. 

  658. <H5>Parameters</H5>
    659. 

  659. <TT>st_thread_exit()</TT> has the following parameters:<P>
    660. 

  660. <TT>retval</TT><P>
    661. 

  661. If the thread is joinable, then the value <TT>retval</TT> may be retrieved
    662. 

  662. by <A HREF=#thread_join>st_thread_join()</A>. If a thread returns from its
    663. 

  663. start function, it acts as if it had called <TT>st_thread_exit()</TT> with 
    664. 

  664. <TT>retval</TT> as the value returned.
    665. 

  665. <P>
    666. 

  666. <H5>Returns</H5>
    667. 

  667. Nothing.
    668. 

  668. <P>
    669. 

  669. <H5>Description</H5>
    670. 

  670. This function terminates the calling thread. When a thread exits, per-thread
    671. 

  671. private data is destroyed by invoking the destructor function for any
    672. 

  672. non-<TT>NULL</TT> thread specific values associated with active keys (see
    673. 

  673. <A HREF=#key_create>st_key_create()</A>). This function is implicitly called
    674. 

  674. when a thread returns from its start function.<P>
    675. 

  675. When the last thread terminates the process exits with a zero status value.
    676. 

  676. <P>
    677. 

  677. <HR>
    678. 

  678. <P>
    679. 

  679. <A NAME="thread_join">
    680. 

  680. <H4>st_thread_join()</H4>
    681. 

  681. </A>
    682. 

  682. Blocks the calling thread until a specified thread terminates.
    683. 

  683. <P>
    684. 

  684. <H5>Syntax</H5>
    685. 

  685. 

  686. <PRE>
    687. 

  687. #include &lt;st.h&gt;
    688. 

  688. 

  689. int st_thread_join(st_thread_t thread, void **retvalp);
    690. 

  690. </PRE>
    691. 

  691. <P>
    692. 

  692. <H5>Parameters</H5>
    693. 

  693. <TT>st_thread_join()</TT> has the following parameters:<P>
    694. 

  694. <TT>thread</TT><P>
    695. 

  695. A valid identifier for the thread that is to be joined.<P>
    696. 

  696. <TT>retvalp</TT><P>
    697. 

  697. If this parameter is not <TT>NULL</TT>, then the exit value of the
    698. 

  698. <TT>thread</TT> will be placed in the location referenced by this parameter
    699. 

  699. (see <A HREF=#thread_exit>st_thread_exit()</A>).
    700. 

  700. <P>
    701. 

  701. <H5>Returns</H5>
    702. 

  702. Upon successful completion, a value of <TT>0</TT> is returned.
    703. 

  703. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    704. 

  704. to indicate the error:<P>
    705. 

  705. <TABLE BORDER=0>
    706. 

  706. <TR><TD><TT>EINVAL</TT></TD><TD>Target thread is unjoinable.</TD></TR>
    707. 

  707. <TR><TD><TT>EINVAL</TT></TD><TD>Other thread already waits on the same
    708. 

  708. joinable thread.</TD></TR>
    709. 

  709. <TR><TD><TT>EDEADLK</TT></TD><TD>Target thread is the same as the
    710. 

  710. calling thread.</TD></TR>
    711. 

  711. <TR><TD><TT>EINTR</TT></TD><TD>Current thread was interrupted by
    712. 

  712. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    713. 

  713. </TABLE>
    714. 

  714. <P>
    715. 

  715. <H5>Description</H5>
    716. 

  716. This function is used to synchronize the termination of a thread and possibly
    717. 

  717. retrieve its exit value. Several threads cannot wait for the same thread
    718. 

  718. to complete - one of the calling threads operates successfully, and the others
    719. 

  719. terminate with the error. The calling thread is not blocked if the target
    720. 

  720. thread has already terminated.
    721. 

  721. <P>
    722. 

  722. <HR>
    723. 

  723. <P>
    724. 

  724. <A NAME="thread_self">
    725. 

  725. <H4>st_thread_self()</H4>
    726. 

  726. </A>
    727. 

  727. Identifies the calling thread.
    728. 

  728. <P>
    729. 

  729. <H5>Syntax</H5>
    730. 

  730. 

  731. <PRE>
    732. 

  732. #include &lt;st.h&gt;
    733. 

  733. 

  734. st_thread_t st_thread_self(void);
    735. 

  735. </PRE>
    736. 

  736. <P>
    737. 

  737. <H5>Parameters</H5>
    738. 

  738. None.
    739. 

  739. <P>
    740. 

  740. <H5>Returns</H5>
    741. 

  741. Always returns a valid reference to the calling thread - a self-identity.
    742. 

  742. <P>
    743. 

  743. <H5>Description</H5>
    744. 

  744. This function identifies the calling thread. This is the same identifier
    745. 

  745. that the creating thread obtains from
    746. 

  746. <A HREF=#thread_create>st_thread_create()</A>.
    747. 

  747. <P>
    748. 

  748. <HR>
    749. 

  749. <P>
    750. 

  750. <A NAME="thread_interrupt">
    751. 

  751. <H4>st_thread_interrupt()</H4>
    752. 

  752. </A>
    753. 

  753. Interrupts a target thread.
    754. 

  754. <P>
    755. 

  755. <H5>Syntax</H5>
    756. 

  756. 

  757. <PRE>
    758. 

  758. #include &lt;st.h&gt;
    759. 

  759. 

  760. void st_thread_interrupt(st_thread_t thread);
    761. 

  761. </PRE>
    762. 

  762. <P>
    763. 

  763. <H5>Parameters</H5>
    764. 

  764. <TT>st_thread_interrupt()</TT> has the following parameters:<P>
    765. 

  765. <TT>thread</TT><P>
    766. 

  766. A valid identifier for the thread being interrupted.
    767. 

  767. <P>
    768. 

  768. <H5>Returns</H5>
    769. 

  769. Nothing.
    770. 

  770. <P>
    771. 

  771. <H5>Description</H5>
    772. 

  772. This function interrupts (unblocks) a target thread that is blocked in one
    773. 

  773. of the <A HREF=#block>blocking functions</A>. A function that was interrupted
    774. 

  774. returns an error and sets <TT>errno</TT> to <TT>EINTR</TT>. It is up to
    775. 

  775. the target thread to act upon an interrupt (e.g., it may exit or just
    776. 

  776. abort the current transaction).<P>
    777. 

  777. <B>Note: </B> State Threads library functions are never interrupted by a
    778. 

  778. caught signal. A blocking library function returns an error and sets
    779. 

  779. <TT>errno</TT> to <TT>EINTR</TT> <I>only</I> if the current thread was
    780. 

  780. interrupted via <TT>st_thread_interrupt()</TT>.
    781. 

  781. <P>
    782. 

  782. If a target thread is already runnable or running (e.g., it is a newly
    783. 

  783. created thread or calling thread itself), this function will prevent it
    784. 

  784. from subsequent blocking. In other words, the interrupt will be "delivered"
    785. 

  785. only when a target thread is about to block.
    786. 

  786. <P>
    787. 

  787. <HR>
    788. 

  788. <P>
    789. 

  789. <A NAME="sleep">
    790. 

  790. <H4>st_sleep(), st_usleep()</H4>
    791. 

  791. </A>
    792. 

  792. Suspends current thread for a specified amount of time.
    793. 

  793. <P>
    794. 

  794. <H5>Syntax</H5>
    795. 

  795. 

  796. <PRE>
    797. 

  797. #include &lt;st.h&gt;
    798. 

  798. 

  799. int st_sleep(int secs);
    800. 

  800. 

  801. int st_usleep(st_utime_t usecs);
    802. 

  802. </PRE>
    803. 

  803. <P>
    804. 

  804. <H5>Parameters</H5>
    805. 

  805. <TT>st_sleep()</TT> has the following parameters:<P>
    806. 

  806. <TT>secs</TT><P>
    807. 

  807. The number of seconds you want the thread to sleep for.
    808. 

  808. <P>
    809. 

  809. <TT>st_usleep()</TT> has the following parameters:<P>
    810. 

  810. <TT>usecs</TT><P>
    811. 

  811. The number of microseconds you want the thread to sleep for. This parameter
    812. 

  812. is a variable of type <A HREF=#utime_t><B>st_utime_t</B></A>.
    813. 

  813. <P>
    814. 

  814. <H5>Returns</H5>
    815. 

  815. Upon successful completion, a value of <TT>0</TT> is returned.
    816. 

  816. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    817. 

  817. to indicate the error:<P>
    818. 

  818. <TABLE BORDER=0>
    819. 

  819. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    820. 

  820. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    821. 

  821. </TABLE>
    822. 

  822. <P>
    823. 

  823. <H5>Description</H5>
    824. 

  824. These functions suspend the calling thread from execution for a specified
    825. 

  825. number of seconds (<TT>st_sleep()</TT>) or microseconds (<TT>st_usleep()</TT>).
    826. 

  826. <P>
    827. 

  827. 

  828. If zero is passed as a parameter to <tt>st_sleep()</tt>, or
    829. 

  829. <tt>ST_UTIME_NO_WAIT</tt> (<tt>0</tt>) is passed to
    830. 

  830. <tt>st_usleep()</tt>, the calling thread yields, thus potentially
    831. 

  831. allowing another thread to run.
    832. 

  832. 

  833. <P>
    834. 

  834. 

  835. If <TT>-1</TT> is passed as a parameter to <tt>st_sleep()</tt>, or
    836. 

  836. <tt>ST_UTIME_NO_TIMEOUT</tt> (<tt>-1</tt>) is passed to
    837. 

  837. <tt>st_usleep()</tt>, the calling thread will be suspended permanently.
    838. 

  838. It can be resumed again by interrupting it via <A
    839. 

  839. HREF=#thread_interrupt>st_thread_interrupt()</A>.
    840. 

  840. 

  841. <P>
    842. 

  842. <HR>
    843. 

  843. <P>
    844. 

  844. <A NAME="randomize_stacks">
    845. 

  845. <H4>st_randomize_stacks()</H4>
    846. 

  846. </A>
    847. 

  847. Turns stack base address randomization on or off.
    848. 

  848. <P>
    849. 

  849. <H5>Syntax</H5>
    850. 

  850. 

  851. <PRE>
    852. 

  852. #include &lt;st.h&gt;
    853. 

  853. 

  854. int st_randomize_stacks(int on);
    855. 

  855. </PRE>
    856. 

  856. <P>
    857. 

  857. <H5>Parameters</H5>
    858. 

  858. <TT>st_randomize_stacks()</TT> has the following parameters:<P>
    859. 

  859. <TT>on</TT><P>
    860. 

  860. If this parameter has a non-zero value, the State Threads library
    861. 

  861. randomizes the base addresses of stacks allocated for threads created
    862. 

  862. after this call.  Otherwise new threads' stacks are typically page
    863. 

  863. aligned.
    864. 

  864. <P>
    865. 

  865. <H5>Returns</H5>
    866. 

  866. The previous state of stack randomization (a value of <TT>0</TT> if it
    867. 

  867. was off and a non-zero value otherwise).
    868. 

  868. <P>
    869. 

  869. <H5>Description</H5>
    870. 

  870. Randomizing state threads' stack bases may improve cache performance on
    871. 

  871. some systems when large numbers of state threads all perform roughly the
    872. 

  872. same work, as when they all start from the same root function.  On many
    873. 

  873. modern systems the performance increase is negligible.  You should
    874. 

  874. compare your application's performance with this feature on and off to
    875. 

  875. see if you really need it.
    876. 

  876. <P>
    877. 

  877. When randomization is enabled, new stacks are allocated one page larger
    878. 

  878. to accomodate the randomization.
    879. 

  879. <P>
    880. 

  880. This call affects only threads created afterward.  It has no effect on
    881. 

  881. existing threads.
    882. 

  882. <P>
    883. 

  883. <HR>
    884. 

  884. <P>
    885. 

  885. 

  886. <A NAME="priv">
    887. 

  887. <H2>Per-Thread Private Data</H2>
    888. 

  888. </A>
    889. 

  889. These functions allow to associate private data with each of the threads in
    890. 

  890. a process.
    891. 

  891. <P>
    892. 

  892. <DL>
    893. 

  893. <DD><A HREF=#key_create>st_key_create()</A></DD>
    894. 

  894. <DD><A HREF=#key_getlimit>st_key_getlimit()</A></DD>
    895. 

  895. <DD><A HREF=#thread_setspecific>st_thread_setspecific()</A></DD>
    896. 

  896. <DD><A HREF=#thread_getspecific>st_thread_getspecific()</A></DD>
    897. 

  897. </DL>
    898. 

  898. <P>
    899. 

  899. <HR>
    900. 

  900. <P>
    901. 

  901. <A NAME="key_create">
    902. 

  902. <H4>st_key_create()</H4>
    903. 

  903. </A>
    904. 

  904. Creates a key (non-negative integer) that can be used by all
    905. 

  905. threads in the process to get and set thread-specific data.
    906. 

  906. <P>
    907. 

  907. <H5>Syntax</H5>
    908. 

  908. 

  909. <PRE>
    910. 

  910. #include &lt;st.h&gt;
    911. 

  911. 

  912. int st_key_create(int *keyp, void (*destructor)(void *));
    913. 

  913. </PRE>
    914. 

  914. <P>
    915. 

  915. <H5>Parameters</H5>
    916. 

  916. <TT>st_key_create()</TT> has the following parameters:<P>
    917. 

  917. <TT>keyp</TT><P>
    918. 

  918. The newly created key is returned in the memory pointed to by this parameter.
    919. 

  919. The new key can be used with
    920. 

  920. <A HREF=#thread_setspecific>st_thread_setspecific()</A> and
    921. 

  921. <A HREF=#thread_getspecific>st_thread_getspecific()</A>.<P>
    922. 

  922. <TT>destructor</TT><P>
    923. 

  923. Specifies an optional destructor function for the private data associated
    924. 

  924. with the key. This function can be specified as <TT>NULL</TT>.
    925. 

  925. Upon thread exit (see <A HREF=#thread_exit>st_thread_exit()</A>), if a key
    926. 

  926. has a non-<TT>NULL</TT> <TT>destructor</TT> and has a non-<TT>NULL</TT> value
    927. 

  927. associated with that key, then the <TT>destructor</TT> function will be
    928. 

  928. called with the associated value.
    929. 

  929. <P>
    930. 

  930. <H5>Returns</H5>
    931. 

  931. Upon successful completion, a value of <TT>0</TT> is returned.
    932. 

  932. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    933. 

  933. to indicate the error:<P>
    934. 

  934. <TABLE BORDER=0>
    935. 

  935. <TR><TD><TT>EAGAIN</TT></TD><TD>The limit on the total number of keys per
    936. 

  936. process has been exceeded (see <A HREF=#key_getlimit>st_key_getlimit()</A>).
    937. 

  937. </TD></TR>
    938. 

  938. </TABLE>
    939. 

  939. <P>
    940. 

  940. <H5>Description</H5>
    941. 

  941. If this function is successful, every thread in the same process is capable
    942. 

  942. of associating private data with the new key. After a new key is created, all
    943. 

  943. active threads have the value <TT>NULL</TT> associated with that key.
    944. 

  944. After a new thread is created, the value <TT>NULL</TT> is associated with
    945. 

  945. all keys for that thread.  If a non-<TT>NULL</TT> destructor function is
    946. 

  946. registered with a new key, it will be called at one of two times, as long as
    947. 

  947. the private data is not <TT>NULL</TT>:
    948. 

  948. <UL>
    949. 

  949. <LI>when replacement private data is set with
    950. 

  950. <A HREF=#thread_setspecific>st_thread_setspecific()</A></LI>
    951. 

  951. <LI>when a thread exits (see <A HREF=#thread_exit>st_thread_exit()</A>)</LI>
    952. 

  952. </UL>
    953. 

  953. <P>
    954. 

  954. The key maintains independent data values for each binding thread. A thread
    955. 

  955. can get access only to its own thread-specific data. There is no way to
    956. 

  956. deallocate a private data key once it is allocated.
    957. 

  957. <P>
    958. 

  958. <HR>
    959. 

  959. <P>
    960. 

  960. <A NAME="key_getlimit">
    961. 

  961. <H4>st_key_getlimit()</H4>
    962. 

  962. </A>
    963. 

  963. Returns the key limit.
    964. 

  964. <P>
    965. 

  965. <H5>Syntax</H5>
    966. 

  966. 

  967. <PRE>
    968. 

  968. #include &lt;st.h&gt;
    969. 

  969. 

  970. int st_key_getlimit(void);
    971. 

  971. </PRE>
    972. 

  972. <P>
    973. 

  973. <H5>Parameters</H5>
    974. 

  974. None.
    975. 

  975. <P>
    976. 

  976. <H5>Returns</H5>
    977. 

  977. The limit on the total number of keys per process.
    978. 

  978. <P>
    979. 

  979. <H5>Description</H5>
    980. 

  980. This function can be used to obtain the limit on the total number of keys
    981. 

  981. per process (see <A HREF=#key_create>st_key_create()</A>).
    982. 

  982. <P>
    983. 

  983. <HR>
    984. 

  984. <P>
    985. 

  985. <A NAME="thread_setspecific">
    986. 

  986. <H4>st_thread_setspecific()</H4>
    987. 

  987. </A>
    988. 

  988. Sets per-thread private data.
    989. 

  989. <P>
    990. 

  990. <H5>Syntax</H5>
    991. 

  991. 

  992. <PRE>
    993. 

  993. #include &lt;st.h&gt;
    994. 

  994. 

  995. int st_thread_setspecific(int key, void *value);
    996. 

  996. </PRE>
    997. 

  997. <P>
    998. 

  998. <H5>Parameters</H5>
    999. 

  999. <TT>st_thread_setspecific()</TT> has the following parameters:<P>
    1000. 

  1000. <TT>key</TT><P>
    1001. 

  1001. This parameter represents a key with which thread-specific data is associated.
    1002. 

  1002. <P>
    1003. 

  1003. <TT>value</TT><P>
    1004. 

  1004. The per-thread private data, or more likely, a pointer to the data which is
    1005. 

  1005. associated with <TT>key</TT>.
    1006. 

  1006. <P>
    1007. 

  1007. <H5>Returns</H5>
    1008. 

  1008. Upon successful completion, a value of <TT>0</TT> is returned.
    1009. 

  1009. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    1010. 

  1010. to indicate the error:<P>
    1011. 

  1011. <TABLE BORDER=0>
    1012. 

  1012. <TR><TD><TT>EINVAL</TT></TD><TD>The specified <TT>key</TT> is invalid.</TD>
    1013. 

  1013. </TR>
    1014. 

  1014. </TABLE>
    1015. 

  1015. <P>
    1016. 

  1016. <H5>Description</H5>
    1017. 

  1017. This function associates a thread-specific <TT>value</TT> with <TT>key</TT>.
    1018. 

  1018. Different threads may bind different values to the same key.<P>
    1019. 

  1019. If the thread already has non-<TT>NULL</TT> private data associated with
    1020. 

  1020. <TT>key</TT>, and if the destructor function for that key is not
    1021. 

  1021. <TT>NULL</TT>, this destructor function will be called before setting the
    1022. 

  1022. new data value.
    1023. 

  1023. <P>
    1024. 

  1024. <HR>
    1025. 

  1025. <P>
    1026. 

  1026. <A NAME="thread_getspecific">
    1027. 

  1027. <H4>st_thread_getspecific()</H4>
    1028. 

  1028. </A>
    1029. 

  1029. Retrieves the per-thread private data for the current thread.
    1030. 

  1030. <P>
    1031. 

  1031. <H5>Syntax</H5>
    1032. 

  1032. 

  1033. <PRE>
    1034. 

  1034. #include &lt;st.h&gt;
    1035. 

  1035. 

  1036. void *st_thread_getspecific(int key);
    1037. 

  1037. </PRE>
    1038. 

  1038. <P>
    1039. 

  1039. <H5>Parameters</H5>
    1040. 

  1040. <TT>st_thread_getspecific()</TT> has the following parameters:<P>
    1041. 

  1041. <TT>key</TT><P>
    1042. 

  1042. This parameter represents a key with which thread-specific data is associated.
    1043. 

  1043. <P>
    1044. 

  1044. <H5>Returns</H5>
    1045. 

  1045. The thread-specific data associated with <TT>key</TT>. If no data is
    1046. 

  1046. associated with <TT>key</TT>, then <TT>NULL</TT> is returned.
    1047. 

  1047. <P>
    1048. 

  1048. <H5>Description</H5>
    1049. 

  1049. This function returns the calling thread's value that is bound to the
    1050. 

  1050. specified <TT>key</TT> (see
    1051. 

  1051. <A HREF=#thread_setspecific>st_thread_setspecific()</A>).
    1052. 

  1052. <P>
    1053. 

  1053. <HR>
    1054. 

  1054. <P>
    1055. 

  1055. 

  1056. <A NAME="sync">
    1057. 

  1057. <H2>Synchronization</H2>
    1058. 

  1058. </A>
    1059. 

  1059. <P>
    1060. 

  1060. These functions operate on <A HREF=#cond_t>condition variables</A>
    1061. 

  1061. and <A HREF=#mutex_t>mutual exclusion locks</A> (mutexes).<P>
    1062. 

  1062. Functions are provided to wait on a condition variable and to wake up
    1063. 

  1063. (signal) threads that are waiting on the condition variable.
    1064. 

  1064. <P>
    1065. 

  1065. <DL>
    1066. 

  1066. <DD><A HREF=#cond_new>st_cond_new()</A></DD>
    1067. 

  1067. <DD><A HREF=#cond_destroy>st_cond_destroy()</A></DD>
    1068. 

  1068. <DD><A HREF=#cond_wait>st_cond_wait()</A></DD>
    1069. 

  1069. <DD><A HREF=#cond_timedwait>st_cond_timedwait()</A></DD>
    1070. 

  1070. <DD><A HREF=#cond_signal>st_cond_signal()</A></DD>
    1071. 

  1071. <DD><A HREF=#cond_broadcast>st_cond_broadcast()</A></DD>
    1072. 

  1072. <P>
    1073. 

  1073. <DD><A HREF=#mutex_new>st_mutex_new()</A></DD>
    1074. 

  1074. <DD><A HREF=#mutex_destroy>st_mutex_destroy()</A></DD>
    1075. 

  1075. <DD><A HREF=#mutex_lock>st_mutex_lock()</A></DD>
    1076. 

  1076. <DD><A HREF=#mutex_trylock>st_mutex_trylock()</A></DD>
    1077. 

  1077. <DD><A HREF=#mutex_unlock>st_mutex_unlock()</A></DD>
    1078. 

  1078. </DL>
    1079. 

  1079. <P>
    1080. 

  1080. <HR>
    1081. 

  1081. <P>
    1082. 

  1082. <A NAME="cond_new">
    1083. 

  1083. <H4>st_cond_new()</H4>
    1084. 

  1084. </A>
    1085. 

  1085. Creates a new condition variable.
    1086. 

  1086. <P>
    1087. 

  1087. <H5>Syntax</H5>
    1088. 

  1088. 

  1089. <PRE>
    1090. 

  1090. #include &lt;st.h&gt;
    1091. 

  1091. 

  1092. st_cond_t st_cond_new(void);
    1093. 

  1093. </PRE>
    1094. 

  1094. <P>
    1095. 

  1095. <H5>Parameters</H5>
    1096. 

  1096. None.
    1097. 

  1097. <P>
    1098. 

  1098. <H5>Returns</H5>
    1099. 

  1099. Upon successful completion, a new condition variable identifier is returned.
    1100. 

  1100. Otherwise, <TT>NULL</TT> is returned and <TT>errno</TT> is set
    1101. 

  1101. to indicate the error.
    1102. 

  1102. <P>
    1103. 

  1103. <H5>Description</H5>
    1104. 

  1104. This function creates a new condition variable.
    1105. 

  1105. <P>
    1106. 

  1106. <HR>
    1107. 

  1107. <P>
    1108. 

  1108. <A NAME="cond_destroy">
    1109. 

  1109. <H4>st_cond_destroy()</H4>
    1110. 

  1110. </A>
    1111. 

  1111. Destroys a condition variable.
    1112. 

  1112. <P>
    1113. 

  1113. <H5>Syntax</H5>
    1114. 

  1114. 

  1115. <PRE>
    1116. 

  1116. #include &lt;st.h&gt;
    1117. 

  1117. 

  1118. int st_cond_destroy(st_cond_t cvar);
    1119. 

  1119. </PRE>
    1120. 

  1120. <P>
    1121. 

  1121. <H5>Parameters</H5>
    1122. 

  1122. <TT>st_cond_destroy()</TT> has the following parameters:<P>
    1123. 

  1123. <TT>cvar</TT><P>
    1124. 

  1124. An identifier of the condition variable object to be destroyed.
    1125. 

  1125. <P>
    1126. 

  1126. <H5>Returns</H5>
    1127. 

  1127. Upon successful completion, a value of <TT>0</TT> is returned.
    1128. 

  1128. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    1129. 

  1129. to indicate the error:<P>
    1130. 

  1130. <TABLE BORDER=0>
    1131. 

  1131. <TR><TD><TT>EBUSY</TT></TD><TD>The condition variable is currently being
    1132. 

  1132. used by one or more threads.</TD>
    1133. 

  1133. </TR>
    1134. 

  1134. </TABLE>
    1135. 

  1135. <P>
    1136. 

  1136. <H5>Description</H5>
    1137. 

  1137. This function destroys a condition variable. The caller is responsible for
    1138. 

  1138. ensuring that the condition variable is no longer in use.
    1139. 

  1139. <P>
    1140. 

  1140. <HR>
    1141. 

  1141. <P>
    1142. 

  1142. <A NAME="cond_wait">
    1143. 

  1143. <H4>st_cond_wait()</H4>
    1144. 

  1144. </A>
    1145. 

  1145. Waits on a condition.
    1146. 

  1146. <P>
    1147. 

  1147. <H5>Syntax</H5>
    1148. 

  1148. 

  1149. <PRE>
    1150. 

  1150. #include &lt;st.h&gt;
    1151. 

  1151. 

  1152. int st_cond_wait(st_cond_t cvar);
    1153. 

  1153. </PRE>
    1154. 

  1154. <P>
    1155. 

  1155. <H5>Parameters</H5>
    1156. 

  1156. <TT>st_cond_wait()</TT> has the following parameters:<P>
    1157. 

  1157. <TT>cvar</TT><P>
    1158. 

  1158. The condition variable on which to wait.
    1159. 

  1159. <P>
    1160. 

  1160. <H5>Returns</H5>
    1161. 

  1161. Upon successful completion, a value of <TT>0</TT> is returned.
    1162. 

  1162. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    1163. 

  1163. to indicate the error:<P>
    1164. 

  1164. <TABLE BORDER=0>
    1165. 

  1165. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    1166. 

  1166. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    1167. 

  1167. </TABLE>
    1168. 

  1168. <P>
    1169. 

  1169. <H5>Description</H5>
    1170. 

  1170. This function is used to block on a condition variable. A return from this
    1171. 

  1171. function does not guarantee that the condition or event for which the caller
    1172. 

  1172. was waiting actually occurred. It is the responsibility of the caller
    1173. 

  1173. to recheck the condition wait predicate before proceeding.<P>
    1174. 

  1174. <B>Note:</B> The State Threads library scheduling guarantees that the
    1175. 

  1175. condition cannot change between the checking and blocking, therefore there
    1176. 

  1176. is no need for mutex protection. You must not call any
    1177. 

  1177. <A HREF=#block>blocking functions</A> between the condition checking and
    1178. 

  1178. the <TT>st_cond_wait()</TT> call.
    1179. 

  1179. <P>
    1180. 

  1180. <HR>
    1181. 

  1181. <P>
    1182. 

  1182. <A NAME="cond_timedwait">
    1183. 

  1183. <H4>st_cond_timedwait()</H4>
    1184. 

  1184. </A>
    1185. 

  1185. Waits on a condition.
    1186. 

  1186. <P>
    1187. 

  1187. <H5>Syntax</H5>
    1188. 

  1188. 

  1189. <PRE>
    1190. 

  1190. #include &lt;st.h&gt;
    1191. 

  1191. 

  1192. int st_cond_timedwait(st_cond_t cvar, st_utime_t timeout);
    1193. 

  1193. </PRE>
    1194. 

  1194. <P>
    1195. 

  1195. <H5>Parameters</H5>
    1196. 

  1196. <TT>st_cond_timedwait()</TT> has the following parameters:<P>
    1197. 

  1197. <TT>cvar</TT><P>
    1198. 

  1198. The condition variable on which to wait.<P>
    1199. 

  1199. <TT>timeout</TT><P>
    1200. 

  1200. If the number of microseconds specified by this parameter passes before the
    1201. 

  1201. waiting thread is signalled, an error is returned. This parameter is a
    1202. 

  1202. variable of type <A HREF=#utime_t><B>st_utime_t</B></A>. Note that this
    1203. 

  1203. time value is a <I>time delta</I>; it is not an <I>absolute time</I>.
    1204. 

  1204. Also note that timeouts are measured <A HREF="notes.html#timeouts">since
    1205. 

  1205. the last context switch</A>.
    1206. 

  1206. <P>
    1207. 

  1207. <H5>Returns</H5>
    1208. 

  1208. Upon successful completion, a value of <TT>0</TT> is returned.
    1209. 

  1209. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    1210. 

  1210. to indicate the error:<P>
    1211. 

  1211. <TABLE BORDER=0>
    1212. 

  1212. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    1213. 

  1213. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    1214. 

  1214. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred before the thread was
    1215. 

  1215. awakened by <A HREF=#cond_signal>st_cond_signal()</A> or
    1216. 

  1216. <A HREF=#cond_broadcast>st_cond_broadcast()</A>.</TD></TR>
    1217. 

  1217. </TABLE>
    1218. 

  1218. <P>
    1219. 

  1219. <H5>Description</H5>
    1220. 

  1220. This function works the same way as <A HREF=#cond_wait>st_cond_wait()</A>,
    1221. 

  1221. except that an error is returned if the number of microseconds specified by
    1222. 

  1222. <TT>timeout</TT> passes before the waiting thread is signalled.
    1223. 

  1223. <P>
    1224. 

  1224. <HR>
    1225. 

  1225. <P>
    1226. 

  1226. <A NAME="cond_signal">
    1227. 

  1227. <H4>st_cond_signal()</H4>
    1228. 

  1228. </A>
    1229. 

  1229. Unblocks a thread waiting on a condition variable.
    1230. 

  1230. <P>
    1231. 

  1231. <H5>Syntax</H5>
    1232. 

  1232. 

  1233. <PRE>
    1234. 

  1234. #include &lt;st.h&gt;
    1235. 

  1235. 

  1236. int st_cond_signal(st_cond_t cvar);
    1237. 

  1237. </PRE>
    1238. 

  1238. <P>
    1239. 

  1239. <H5>Parameters</H5>
    1240. 

  1240. <TT>st_cond_signal()</TT> has the following parameters:<P>
    1241. 

  1241. <TT>cvar</TT><P>
    1242. 

  1242. The condition variable to signal.
    1243. 

  1243. <P>
    1244. 

  1244. <H5>Returns</H5>
    1245. 

  1245. Always zero.
    1246. 

  1246. <P>
    1247. 

  1247. <H5>Description</H5>
    1248. 

  1248. This function unblocks (signals) one of the threads that are blocked on
    1249. 

  1249. <TT>cvar</TT> at the time of the call.  If no thread is waiting on the
    1250. 

  1250. condition variable, the signal operation is a no-op.
    1251. 

  1251. <P>
    1252. 

  1252. <HR>
    1253. 

  1253. <P>
    1254. 

  1254. <A NAME="cond_broadcast">
    1255. 

  1255. <H4>st_cond_broadcast()</H4>
    1256. 

  1256. </A>
    1257. 

  1257. Unblocks all threads waiting on a condition variable.
    1258. 

  1258. <P>
    1259. 

  1259. <H5>Syntax</H5>
    1260. 

  1260. 

  1261. <PRE>
    1262. 

  1262. #include &lt;st.h&gt;
    1263. 

  1263. 

  1264. int st_cond_broadcast(st_cond_t cvar);
    1265. 

  1265. </PRE>
    1266. 

  1266. <P>
    1267. 

  1267. <H5>Parameters</H5>
    1268. 

  1268. <TT>st_cond_broadcast()</TT> has the following parameters:<P>
    1269. 

  1269. <TT>cvar</TT><P>
    1270. 

  1270. The condition variable to broadcast.
    1271. 

  1271. <P>
    1272. 

  1272. <H5>Returns</H5>
    1273. 

  1273. Always zero.
    1274. 

  1274. <P>
    1275. 

  1275. <H5>Description</H5>
    1276. 

  1276. This function unblocks all threads blocked on the specified condition
    1277. 

  1277. variable at the time of the call. If no threads are waiting, this operation
    1278. 

  1278. is a no-op.
    1279. 

  1279. <P>
    1280. 

  1280. <HR>
    1281. 

  1281. <P>
    1282. 

  1282. 

  1283. <A NAME="mutex_new">
    1284. 

  1284. <H4>st_mutex_new()</H4>
    1285. 

  1285. </A>
    1286. 

  1286. Creates a new mutual exclusion lock (mutex).
    1287. 

  1287. <P>
    1288. 

  1288. <H5>Syntax</H5>
    1289. 

  1289. 

  1290. <PRE>
    1291. 

  1291. #include &lt;st.h&gt;
    1292. 

  1292. 

  1293. st_mutex_t st_mutex_new(void);
    1294. 

  1294. </PRE>
    1295. 

  1295. <P>
    1296. 

  1296. <H5>Parameters</H5>
    1297. 

  1297. None.
    1298. 

  1298. <P>
    1299. 

  1299. <H5>Returns</H5>
    1300. 

  1300. Upon successful completion, a new mutex identifier is returned.
    1301. 

  1301. Otherwise, <TT>NULL</TT> is returned and <TT>errno</TT> is set to
    1302. 

  1302. indicate the error.
    1303. 

  1303. <P>
    1304. 

  1304. <H5>Description</H5>
    1305. 

  1305. This function creates a new opaque mutual exclusion lock (see
    1306. 

  1306. <A HREF=#mutex_t><B>st_mutex_t</B></A>).
    1307. 

  1307. <P>
    1308. 

  1308. <HR>
    1309. 

  1309. <P>
    1310. 

  1310. <A NAME="mutex_destroy">
    1311. 

  1311. <H4>st_mutex_destroy()</H4>
    1312. 

  1312. </A>
    1313. 

  1313. Destroys a specified mutex object.
    1314. 

  1314. <P>
    1315. 

  1315. <H5>Syntax</H5>
    1316. 

  1316. 

  1317. <PRE>
    1318. 

  1318. #include &lt;st.h&gt;
    1319. 

  1319. 

  1320. int st_mutex_destroy(st_mutex_t lock);
    1321. 

  1321. </PRE>
    1322. 

  1322. <P>
    1323. 

  1323. <H5>Parameters</H5>
    1324. 

  1324. <TT>st_mutex_destroy()</TT> has the following parameters:<P>
    1325. 

  1325. <TT>lock</TT><P>
    1326. 

  1326. An identifier of the mutex object to be destroyed.
    1327. 

  1327. <P>
    1328. 

  1328. <H5>Returns</H5>
    1329. 

  1329. Upon successful completion, a value of <TT>0</TT> is returned.
    1330. 

  1330. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    1331. 

  1331. to indicate the error:<P>
    1332. 

  1332. <TABLE BORDER=0>
    1333. 

  1333. <TR><TD><TT>EBUSY</TT></TD><TD>The mutex is currently being used by
    1334. 

  1334. other threads.</TD>
    1335. 

  1335. </TR>
    1336. 

  1336. </TABLE>
    1337. 

  1337. <P>
    1338. 

  1338. <H5>Description</H5>
    1339. 

  1339. This function destroys a mutex. The caller is responsible for ensuring
    1340. 

  1340. that the mutex is no longer in use.
    1341. 

  1341. <P>
    1342. 

  1342. <HR>
    1343. 

  1343. <P>
    1344. 

  1344. <A NAME="mutex_lock">
    1345. 

  1345. <H4>st_mutex_lock()</H4>
    1346. 

  1346. </A>
    1347. 

  1347. Locks a specified mutex object.
    1348. 

  1348. <P>
    1349. 

  1349. <H5>Syntax</H5>
    1350. 

  1350. 

  1351. <PRE>
    1352. 

  1352. #include &lt;st.h&gt;
    1353. 

  1353. 

  1354. int st_mutex_lock(st_mutex_t lock);
    1355. 

  1355. </PRE>
    1356. 

  1356. <P>
    1357. 

  1357. <H5>Parameters</H5>
    1358. 

  1358. <TT>st_mutex_lock()</TT> has the following parameters:<P>
    1359. 

  1359. <TT>lock</TT><P>
    1360. 

  1360. An identifier of the mutex object to be locked.
    1361. 

  1361. <P>
    1362. 

  1362. <H5>Returns</H5>
    1363. 

  1363. Upon successful completion, a value of <TT>0</TT> is returned.
    1364. 

  1364. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    1365. 

  1365. to indicate the error:<P>
    1366. 

  1366. <TABLE BORDER=0>
    1367. 

  1367. <TR><TD><TT>EDEADLK</TT></TD><TD>The current thread already owns the mutex.
    1368. 

  1368. </TD></TR>
    1369. 

  1369. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    1370. 

  1370. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    1371. 

  1371. </TABLE>
    1372. 

  1372. <P>
    1373. 

  1373. <H5>Description</H5>
    1374. 

  1374. A thread that calls this function will block until it can gain exclusive
    1375. 

  1375. ownership of a mutex, and retains ownership until it calls
    1376. 

  1376. <A HREF=#mutex_unlock>st_mutex_unlock()</A>.
    1377. 

  1377. <P>
    1378. 

  1378. <HR>
    1379. 

  1379. <P>
    1380. 

  1380. <A NAME="mutex_trylock">
    1381. 

  1381. <H4>st_mutex_trylock()</H4>
    1382. 

  1382. </A>
    1383. 

  1383. Attempts to acquire a mutex.
    1384. 

  1384. <P>
    1385. 

  1385. <H5>Syntax</H5>
    1386. 

  1386. 

  1387. <PRE>
    1388. 

  1388. #include &lt;st.h&gt;
    1389. 

  1389. 

  1390. int st_mutex_trylock(st_mutex_t lock);
    1391. 

  1391. </PRE>
    1392. 

  1392. <P>
    1393. 

  1393. <H5>Parameters</H5>
    1394. 

  1394. <TT>st_mutex_trylock()</TT> has the following parameters:<P>
    1395. 

  1395. <TT>lock</TT><P>
    1396. 

  1396. An identifier of the mutex object to be locked.
    1397. 

  1397. <P>
    1398. 

  1398. <H5>Returns</H5>
    1399. 

  1399. Upon successful completion, a value of <TT>0</TT> is returned.
    1400. 

  1400. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    1401. 

  1401. to indicate the error:<P>
    1402. 

  1402. <TABLE BORDER=0>
    1403. 

  1403. <TR><TD><TT>EBUSY</TT></TD><TD>The mutex is currently held by another
    1404. 

  1404. thread.</TD></TR>
    1405. 

  1405. </TABLE>
    1406. 

  1406. <P>
    1407. 

  1407. <H5>Description</H5>
    1408. 

  1408. This function attempts to acquire a mutex. If the mutex object is locked
    1409. 

  1409. (by any thread, including the current thread), the call returns immediately
    1410. 

  1410. with an error.
    1411. 

  1411. <P>
    1412. 

  1412. <HR>
    1413. 

  1413. <P>
    1414. 

  1414. <A NAME="mutex_unlock">
    1415. 

  1415. <H4>st_mutex_unlock()</H4>
    1416. 

  1416. </A>
    1417. 

  1417. Releases a specified mutex object.
    1418. 

  1418. <P>
    1419. 

  1419. <H5>Syntax</H5>
    1420. 

  1420. 

  1421. <PRE>
    1422. 

  1422. #include &lt;st.h&gt;
    1423. 

  1423. 

  1424. int st_mutex_unlock(st_mutex_t lock);
    1425. 

  1425. </PRE>
    1426. 

  1426. <P>
    1427. 

  1427. <H5>Parameters</H5>
    1428. 

  1428. <TT>st_mutex_unlock()</TT> has the following parameters:<P>
    1429. 

  1429. <TT>lock</TT><P>
    1430. 

  1430. An identifier of the mutex object to be unlocked.
    1431. 

  1431. <P>
    1432. 

  1432. <H5>Returns</H5>
    1433. 

  1433. Upon successful completion, a value of <TT>0</TT> is returned.
    1434. 

  1434. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    1435. 

  1435. to indicate the error:<P>
    1436. 

  1436. <TABLE BORDER=0>
    1437. 

  1437. <TR><TD><TT>EPERM</TT></TD><TD>The current thread does not own the mutex.
    1438. 

  1438. </TD></TR>
    1439. 

  1439. </TABLE>
    1440. 

  1440. <P>
    1441. 

  1441. <H5>Description</H5>
    1442. 

  1442. This function releases a specified mutex object previously acquired by
    1443. 

  1443. <A HREF=#mutex_lock>st_mutex_lock()</A> or
    1444. 

  1444. <A HREF=#mutex_trylock>st_mutex_trylock()</A>. Only the thread that locked
    1445. 

  1445. a mutex should unlock it.
    1446. 

  1446. <P>
    1447. 

  1447. <HR>
    1448. 

  1448. <P>
    1449. 

  1449. 

  1450. <A NAME="timing">
    1451. 

  1451. <H2>Timing</H2>
    1452. 

  1452. </A>
    1453. 

  1453. <P>
    1454. 

  1454. <DL>
    1455. 

  1455. <DD><A HREF=#utime>st_utime()</A></DD>
    1456. 

  1456. <DD><A HREF=#set_utime_function>st_set_utime_function()</A></DD>
    1457. 

  1457. <DD><A HREF=#timecache_set>st_timecache_set()</A></DD>
    1458. 

  1458. <DD><A HREF=#time>st_time()</A></DD>
    1459. 

  1459. </DL>
    1460. 

  1460. <P>
    1461. 

  1461. <HR>
    1462. 

  1462. <P>
    1463. 

  1463. <A NAME="utime">
    1464. 

  1464. <H4>st_utime()</H4>
    1465. 

  1465. </A>
    1466. 

  1466. Returns current high-resolution time.
    1467. 

  1467. <P>
    1468. 

  1468. <H5>Syntax</H5>
    1469. 

  1469. 

  1470. <PRE>
    1471. 

  1471. #include &lt;st.h&gt;
    1472. 

  1472. 

  1473. st_utime_t st_utime(void);
    1474. 

  1474. </PRE>
    1475. 

  1475. <P>
    1476. 

  1476. <H5>Parameters</H5>
    1477. 

  1477. None.
    1478. 

  1478. <P>
    1479. 

  1479. <H5>Returns</H5>
    1480. 

  1480. Current high-resolution time value of type
    1481. 

  1481. <A HREF=#utime_t><B>st_utime_t</B></A>.
    1482. 

  1482. <P>
    1483. 

  1483. <H5>Description</H5>
    1484. 

  1484. This function returns the current high-resolution time. Time is
    1485. 

  1485. expressed as microseconds since some arbitrary time in the past. It is
    1486. 

  1486. not correlated in any way to the time of day.  See also <A
    1487. 

  1487. HREF=#utime_t><B>st_utime_t</B></A> and <A
    1488. 

  1488. HREF="#time"><B>st_time()</B></A>.
    1489. 

  1489. <P>
    1490. 

  1490. <HR>
    1491. 

  1491. <P>
    1492. 

  1492. <A NAME="set_utime_function">
    1493. 

  1493. <H4>st_set_utime_function()</H4>
    1494. 

  1494. </A>
    1495. 

  1495. Set high-resolution time function.
    1496. 

  1496. <P>
    1497. 

  1497. <H5>Syntax</H5>
    1498. 

  1498. 

  1499. <PRE>
    1500. 

  1500. #include &lt;st.h&gt;
    1501. 

  1501. 

  1502. int st_set_utime_function(st_utime_t (*func)(void));
    1503. 

  1503. </PRE>
    1504. 

  1504. <P>
    1505. 

  1505. <H5>Parameters</H5>
    1506. 

  1506. <TT>st_set_utime_function()</TT> has the following parameters:<P>
    1507. 

  1507. <TT>func</TT><P>
    1508. 

  1508. This function will be called to get high-resolution time instead of the
    1509. 

  1509. default <A HREF=#utime>st_utime()</A> function. It must return
    1510. 

  1510. number of microseconds since some arbitrary time in the past.
    1511. 

  1511. <P>
    1512. 

  1512. <H5>Returns</H5>
    1513. 

  1513. Upon successful completion, a value of <TT>0</TT> is returned.
    1514. 

  1514. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    1515. 

  1515. to <TT>EINVAL</TT> to indicate the error.
    1516. 

  1516. <P>
    1517. 

  1517. <H5>Description</H5>
    1518. 

  1518. This function may be called to replace the default implementation of the
    1519. 

  1519. <A HREF=#utime>st_utime()</A> function.  It must be called before the ST
    1520. 

  1520. library has been initialized (see <A HREF=#st_init>st_init()</A>).
    1521. 

  1521. The user-provided function <TT>func</TT> will be invoked whenever
    1522. 

  1522. <A HREF=#utime>st_utime()</A> is called to obtain current high-resolution time.
    1523. 

  1523. Replacing default implementation may be useful, for example, for taking
    1524. 

  1524. advantage of high performance CPU cycle counters.
    1525. 

  1525. <P>
    1526. 

  1526. <HR>
    1527. 

  1527. <P>
    1528. 

  1528. <A NAME="timecache_set">
    1529. 

  1529. <H4>st_timecache_set()</H4>
    1530. 

  1530. </A>
    1531. 

  1531. Turns the time caching on or off.
    1532. 

  1532. <P>
    1533. 

  1533. <H5>Syntax</H5>
    1534. 

  1534. 

  1535. <PRE>
    1536. 

  1536. #include &lt;st.h&gt;
    1537. 

  1537. 

  1538. int st_timecache_set(int on);
    1539. 

  1539. </PRE>
    1540. 

  1540. <P>
    1541. 

  1541. <H5>Parameters</H5>
    1542. 

  1542. <TT>st_timecache_set()</TT> has the following parameters:<P>
    1543. 

  1543. <TT>on</TT><P>
    1544. 

  1544. If this parameter has a non-zero value, the time caching is turned on
    1545. 

  1545. (enabled). Otherwise, the time caching is turned off (disabled).
    1546. 

  1546. By default time caching is disabled.
    1547. 

  1547. <P>
    1548. 

  1548. <H5>Returns</H5>
    1549. 

  1549. The previous state of time caching (a value of <TT>0</TT> if it was off and
    1550. 

  1550. a value of <TT>1</TT> otherwise).
    1551. 

  1551. <P>
    1552. 

  1552. <H5>Description</H5>
    1553. 

  1553. The State Threads library has the ability to "cache" the time value that is
    1554. 

  1554. reported by the <TT>time(2)</TT> system call. If the time caching is enabled
    1555. 

  1555. by calling this function with a non-zero argument, then the result value
    1556. 

  1556. of <TT>time(2)</TT> will be stored and updated at most once per second. The
    1557. 

  1557. cached time can be retrieved by <A HREF=#time>st_time()</A>.
    1558. 

  1558. By default time caching is disabled.
    1559. 

  1559. You may enable or disable time caching at any time but generally
    1560. 

  1560. you enable it once (if desired) during program initialization.<P>
    1561. 

  1561. <B>Note:</B> There are some pathological cases (e.g., very heavy loads during
    1562. 

  1562. application benchmarking) when a single thread runs for a long time without
    1563. 

  1563. giving up control and the cached time value is not updated properly. If you
    1564. 

  1564. <I>always</I> need "real-time" time values, don't enable the time caching.
    1565. 

  1565. <P>
    1566. 

  1566. <HR>
    1567. 

  1567. <P>
    1568. 

  1568. <A NAME="time">
    1569. 

  1569. <H4>st_time()</H4>
    1570. 

  1570. </A>
    1571. 

  1571. Returns the value of time in seconds since 00:00:00 UTC, January 1, 1970.
    1572. 

  1572. <P>
    1573. 

  1573. <H5>Syntax</H5>
    1574. 

  1574. 

  1575. <PRE>
    1576. 

  1576. #include &lt;st.h&gt;
    1577. 

  1577. 

  1578. time_t st_time(void);
    1579. 

  1579. </PRE>
    1580. 

  1580. <P>
    1581. 

  1581. <H5>Parameters</H5>
    1582. 

  1582. None.
    1583. 

  1583. <P>
    1584. 

  1584. <H5>Returns</H5>
    1585. 

  1585. The value of time in seconds since 00:00:00 UTC, January 1, 1970 as reported
    1586. 

  1586. by the <TT>time(2)</TT> system call.
    1587. 

  1587. <P>
    1588. 

  1588. <H5>Description</H5>
    1589. 

  1589. If the time caching was enabled by
    1590. 

  1590. <A HREF=#timecache_set>st_timecache_set()</A>, then this function returns
    1591. 

  1591. the cached result. Otherwise, it just calls <TT>time(2)</TT>.
    1592. 

  1592. <P>
    1593. 

  1593. <HR>
    1594. 

  1594. <P>
    1595. 

  1595. 

  1596. <A NAME="io">
    1597. 

  1597. <H2>I/O Functions</H2>
    1598. 

  1598. </A>
    1599. 

  1599. <P>
    1600. 

  1600. Most State Threads library I/O functions look like corresponding C library
    1601. 

  1601. functions with two exceptions:
    1602. 

  1602. <UL>
    1603. 

  1603. <LI>They operate on file descriptor objects of type
    1604. 

  1604. <A HREF=#netfd_t><B>st_netfd_t</B></A>.</LI>
    1605. 

  1605. <LI>They take an additional argument of type
    1606. 

  1606. <A HREF=#utime_t><B>st_utime_t</B></A> which represents an <I>inactivity
    1607. 

  1607. timeout</I>: if no I/O is possible during this amount of time, I/O functions
    1608. 

  1608. return an error code and set <TT>errno</TT> to <TT>ETIME</TT>.
    1609. 

  1609. 

  1610. The boundary values <tt>ST_UTIME_NO_WAIT</tt> (<TT>0</TT>) and
    1611. 

  1611. <tt>ST_UTIME_NO_TIMEOUT</tt> (<TT>-1</TT>) for this argument indicate
    1612. 

  1612. that the thread should wait no time (function returns immediately) or
    1613. 

  1613. wait forever (never time out), respectively.
    1614. 

  1614. 

  1615. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    1616. 

  1616. last context switch</A>.
    1617. 

  1617. </LI>
    1618. 

  1618. </UL>
    1619. 

  1619. <P>
    1620. 

  1620. <DL>
    1621. 

  1621. <DD><A HREF=#netfd_open>st_netfd_open()</A></DD>
    1622. 

  1622. <DD><A HREF=#netfd_open_socket>st_netfd_open_socket()</A></DD>
    1623. 

  1623. <DD><A HREF=#netfd_free>st_netfd_free()</A></DD>
    1624. 

  1624. <DD><A HREF=#netfd_close>st_netfd_close()</A></DD>
    1625. 

  1625. <DD><A HREF=#netfd_fileno>st_netfd_fileno()</A></DD>
    1626. 

  1626. <DD><A HREF=#netfd_setspecific>st_netfd_setspecific()</A></DD>
    1627. 

  1627. <DD><A HREF=#netfd_getspecific>st_netfd_getspecific()</A></DD>
    1628. 

  1628. <DD><A HREF=#netfd_serialize_accept>st_netfd_serialize_accept()</A></DD>
    1629. 

  1629. <DD><A HREF=#netfd_poll>st_netfd_poll()</A></DD>
    1630. 

  1630. <P>
    1631. 

  1631. <DD><A HREF=#accept>st_accept()</A></DD>
    1632. 

  1632. <DD><A HREF=#connect>st_connect()</A></DD>
    1633. 

  1633. <DD><A HREF=#read>st_read()</A></DD>
    1634. 

  1634. <DD><A HREF=#read_fully>st_read_fully()</A></DD>
    1635. 

  1635. <DD><A HREF=#read_resid>st_read_resid()</A></DD>
    1636. 

  1636. <DD><A HREF=#readv>st_readv()</A></DD>
    1637. 

  1637. <DD><A HREF=#readv_resid>st_read_resid()</A></DD>
    1638. 

  1638. <DD><A HREF=#write>st_write()</A></DD>
    1639. 

  1639. <DD><A HREF=#write_resid>st_write_resid()</A></DD>
    1640. 

  1640. <DD><A HREF=#writev>st_writev()</A></DD>
    1641. 

  1641. <DD><A HREF=#writev_resid>st_writev_resid()</A></DD>
    1642. 

  1642. <DD><A HREF=#recvfrom>st_recvfrom()</A></DD>
    1643. 

  1643. <DD><A HREF=#sendto>st_sendto()</A></DD>
    1644. 

  1644. <DD><A HREF=#recvmsg>st_recvmsg()</A></DD>
    1645. 

  1645. <DD><A HREF=#sendmsg>st_sendmsg()</A></DD>
    1646. 

  1646. <DD><A HREF=#open>st_open()</A></DD>
    1647. 

  1647. <DD><A HREF=#poll>st_poll()</A></DD>
    1648. 

  1648. </DL>
    1649. 

  1649. <P>
    1650. 

  1650. <HR>
    1651. 

  1651. <P>
    1652. 

  1652. <A NAME="netfd_open">
    1653. 

  1653. <H4>st_netfd_open()</H4>
    1654. 

  1654. </A>
    1655. 

  1655. Creates a new file descriptor object.
    1656. 

  1656. <P>
    1657. 

  1657. <H5>Syntax</H5>
    1658. 

  1658. 

  1659. <PRE>
    1660. 

  1660. #include &lt;st.h&gt;
    1661. 

  1661. 

  1662. st_netfd_t st_netfd_open(int osfd);
    1663. 

  1663. </PRE>
    1664. 

  1664. <P>
    1665. 

  1665. <H5>Parameters</H5>
    1666. 

  1666. <TT>st_netfd_open()</TT> has the following parameters:<P>
    1667. 

  1667. <TT>osfd</TT><P>
    1668. 

  1668. 

  1669. Any open OS file descriptor; can be obtained from calls to
    1670. 

  1670. functions including, but not restricted to, <TT>pipe(2), socket(3),
    1671. 

  1671. socketpair(3), fcntl(2), dup(2),</TT> etc.
    1672. 

  1672. 

  1673. 

  1674. <P>
    1675. 

  1675. <H5>Returns</H5>
    1676. 

  1676. Upon successful completion, a new file descriptor object identifier is
    1677. 

  1677. returned. Otherwise, <TT>NULL</TT> is returned and <TT>errno</TT> is set
    1678. 

  1678. to indicate the error.
    1679. 

  1679. <P>
    1680. 

  1680. <H5>Description</H5>
    1681. 

  1681. This function creates a new file descriptor object of type
    1682. 

  1682. <A HREF=#netfd_t><B>st_netfd_t</B></A>.<P>
    1683. 

  1683. 

  1684. <B>Note:</B> Among other things, this function sets a non-blocking
    1685. 

  1685. flag on the underlying OS file descriptor. You should not modify this
    1686. 

  1686. flag directly. Also, once an <A HREF=#netfd_t><B>st_netfd_t</B></A>
    1687. 

  1687. has been created with a given file descriptor, you should avoid
    1688. 

  1688. passing that descriptor to normal I/O or stdio functions. Since the
    1689. 

  1689. O_NONBLOCK flag is shared across <TT>dup(2)</TT>, this applies to
    1690. 

  1690. <TT>dup()</TT>'ed file descriptors as well - for instance, if you pass
    1691. 

  1691. standard output or standard input to <TT>st_netfd_open()</TT>, then
    1692. 

  1692. you should use <A HREF=#write>st_write()</A> instead of <TT>write</TT>
    1693. 

  1693. or <TT>fprintf</TT> when writing to standard error as well - since all
    1694. 

  1694. three descriptors could point to the same terminal. If necessary, you
    1695. 

  1695. can still use <TT>write</TT> directly if you remember to check
    1696. 

  1696. <TT>errno</TT> for <TT>EAGAIN</TT>, but <TT>fprintf</TT> and other
    1697. 

  1697. stdio functions should be avoided completely because, at least on
    1698. 

  1698. Linux, the stdio library cannot be made to work reliably with
    1699. 

  1699. non-blocking files. (This only applies to file descriptors which are
    1700. 

  1700. passed to <TT>st_netfd_open()</TT> or <A
    1701. 

  1701. HREF=#netfd_open_socket>st_netfd_open_socket()</A>, or which are
    1702. 

  1702. related to such descriptors through <TT>dup()</TT>; other file
    1703. 

  1703. descriptors are untouched by State Threads.)
    1704. 

  1704. <P>
    1705. 

  1705. <HR>
    1706. 

  1706. <P>
    1707. 

  1707. <A NAME="netfd_open_socket">
    1708. 

  1708. <H4>st_netfd_open_socket()</H4>
    1709. 

  1709. </A>
    1710. 

  1710. Creates a new file descriptor object from a socket.
    1711. 

  1711. <P>
    1712. 

  1712. <H5>Syntax</H5>
    1713. 

  1713. 

  1714. <PRE>
    1715. 

  1715. #include &lt;st.h&gt;
    1716. 

  1716. 

  1717. st_netfd_t st_netfd_open_socket(int osfd);
    1718. 

  1718. </PRE>
    1719. 

  1719. <P>
    1720. 

  1720. <H5>Parameters</H5>
    1721. 

  1721. <TT>st_netfd_open_socket()</TT> has the following parameters:<P>
    1722. 

  1722. <TT>osfd</TT><P>
    1723. 

  1723. An open OS file descriptor which is a socket initially obtained from a<TT>
    1724. 

  1724. socket(3) or socketpair(3)</TT> call.
    1725. 

  1725. <P>
    1726. 

  1726. <H5>Returns</H5>
    1727. 

  1727. Upon successful completion, a new file descriptor object identifier is
    1728. 

  1728. returned. Otherwise, <TT>NULL</TT> is returned and <TT>errno</TT> is set
    1729. 

  1729. to indicate the error.
    1730. 

  1730. <P>
    1731. 

  1731. <H5>Description</H5>
    1732. 

  1732. This function creates a new file descriptor object of type
    1733. 

  1733. <A HREF=#netfd_t><B>st_netfd_t</B></A> which represents an open end
    1734. 

  1734. point of network communication.<P>
    1735. 

  1735. Unlike the <A HREF=#netfd_open>st_netfd_open()</A> function which may be used
    1736. 

  1736. on OS file descriptors of any origin, <TT>st_netfd_open_socket()</TT> must
    1737. 

  1737. be used only on sockets. It is slightly more efficient than
    1738. 

  1738. <A HREF=#netfd_open>st_netfd_open()</A>.<P>
    1739. 

  1739. <B>Note:</B> Among other things, this function sets a non-blocking flag
    1740. 

  1740. on the underlying OS socket. You should not modify this flag directly.
    1741. 

  1741. See <A HREF=#netfd_open>st_netfd_open()</A>.
    1742. 

  1742. <P>
    1743. 

  1743. <HR>
    1744. 

  1744. <P>
    1745. 

  1745. <A NAME="netfd_free">
    1746. 

  1746. <H4>st_netfd_free()</H4>
    1747. 

  1747. </A>
    1748. 

  1748. Frees a file descriptor object without closing the underlying OS file
    1749. 

  1749. descriptor.
    1750. 

  1750. <P>
    1751. 

  1751. <H5>Syntax</H5>
    1752. 

  1752. 

  1753. <PRE>
    1754. 

  1754. #include &lt;st.h&gt;
    1755. 

  1755. 

  1756. void st_netfd_free(st_netfd_t fd);
    1757. 

  1757. </PRE>
    1758. 

  1758. <P>
    1759. 

  1759. <H5>Parameters</H5>
    1760. 

  1760. <TT>st_netfd_free()</TT> has the following parameters:<P>
    1761. 

  1761. <TT>fd</TT><P>
    1762. 

  1762. A file descriptor object identifier (see
    1763. 

  1763. <A HREF=#netfd_t><B>st_netfd_t</B></A>).
    1764. 

  1764. <P>
    1765. 

  1765. <H5>Returns</H5>
    1766. 

  1766. Nothing.
    1767. 

  1767. <P>
    1768. 

  1768. <H5>Description</H5>
    1769. 

  1769. This function frees the memory and other resources identified by the
    1770. 

  1770. <TT>fd</TT> parameter without closing the underlying OS file descriptor.
    1771. 

  1771. Any non-<TT>NULL</TT> descriptor-specific data is destroyed by invoking
    1772. 

  1772. the specified destructor function (see <A
    1773. 

  1773. HREF=#netfd_setspecific>st_netfd_setspecific()</A>).<P> A thread should
    1774. 

  1774. not free file descriptor objects that are in use by other threads
    1775. 

  1775. because it may lead to unpredictable results (e.g., a freed file
    1776. 

  1776. descriptor may be reused without other threads knowing that).
    1777. 

  1777. <P>
    1778. 

  1778. <HR>
    1779. 

  1779. <P>
    1780. 

  1780. <A NAME="netfd_close">
    1781. 

  1781. <H4>st_netfd_close()</H4>
    1782. 

  1782. </A>
    1783. 

  1783. Closes a file descriptor.
    1784. 

  1784. <P>
    1785. 

  1785. <H5>Syntax</H5>
    1786. 

  1786. 

  1787. <PRE>
    1788. 

  1788. #include &lt;st.h&gt;
    1789. 

  1789. 

  1790. int st_netfd_close(st_netfd_t fd);
    1791. 

  1791. </PRE>
    1792. 

  1792. <P>
    1793. 

  1793. <H5>Parameters</H5>
    1794. 

  1794. <TT>st_netfd_close()</TT> has the following parameters:<P>
    1795. 

  1795. <TT>fd</TT><P>
    1796. 

  1796. A file descriptor object identifier (see
    1797. 

  1797. <A HREF=#netfd_t><B>st_netfd_t</B></A>).
    1798. 

  1798. <P>
    1799. 

  1799. <H5>Returns</H5>
    1800. 

  1800. Upon successful completion, a value of <TT>0</TT> is returned.
    1801. 

  1801. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    1802. 

  1802. to indicate the error.
    1803. 

  1803. <P>
    1804. 

  1804. <H5>Description</H5>
    1805. 

  1805. This function closes the underlying OS file descriptor, frees the memory and
    1806. 

  1806. other resources identified by the <TT>fd</TT> parameter. Any non-<TT>NULL</TT>
    1807. 

  1807. descriptor-specific data is destroyed by invoking the specified destructor
    1808. 

  1808. function (see <A HREF=#netfd_setspecific>st_netfd_setspecific()</A>).<P>
    1809. 

  1809. A thread should not close file descriptor objects that are in use by other
    1810. 

  1810. threads because it may lead to unpredictable results (e.g., a closed
    1811. 

  1811. file descriptor may be reused without other threads knowing that).
    1812. 

  1812. <P>
    1813. 

  1813. <HR>
    1814. 

  1814. <P>
    1815. 

  1815. <A NAME="netfd_fileno">
    1816. 

  1816. <H4>st_netfd_fileno()</H4>
    1817. 

  1817. </A>
    1818. 

  1818. Returns an underlying OS file descriptor.
    1819. 

  1819. <P>
    1820. 

  1820. <H5>Syntax</H5>
    1821. 

  1821. 

  1822. <PRE>
    1823. 

  1823. #include &lt;st.h&gt;
    1824. 

  1824. 

  1825. int st_netfd_fileno(st_netfd_t fd);
    1826. 

  1826. </PRE>
    1827. 

  1827. <P>
    1828. 

  1828. <H5>Parameters</H5>
    1829. 

  1829. <TT>st_netfd_fileno()</TT> has the following parameters:<P>
    1830. 

  1830. <TT>fd</TT><P>
    1831. 

  1831. A file descriptor object identifier (see
    1832. 

  1832. <A HREF=#netfd_t><B>st_netfd_t</B></A>).
    1833. 

  1833. <P>
    1834. 

  1834. <H5>Returns</H5>
    1835. 

  1835. An underlying OS file descriptor.
    1836. 

  1836. <P>
    1837. 

  1837. <H5>Description</H5>
    1838. 

  1838. This function returns the integer OS file descriptor associated with the named
    1839. 

  1839. file descriptor object.
    1840. 

  1840. <P>
    1841. 

  1841. <HR>
    1842. 

  1842. <P>
    1843. 

  1843. <A NAME="netfd_setspecific">
    1844. 

  1844. <H4>st_netfd_setspecific()</H4>
    1845. 

  1845. </A>
    1846. 

  1846. Sets per-descriptor private data.
    1847. 

  1847. <P>
    1848. 

  1848. <H5>Syntax</H5>
    1849. 

  1849. 

  1850. <PRE>
    1851. 

  1851. #include &lt;st.h&gt;
    1852. 

  1852. 

  1853. void st_netfd_setspecific(st_netfd_t fd, void *value,
    1854. 

  1854.                           void (*destructor)(void *));
    1855. 

  1855. </PRE>
    1856. 

  1856. <P>
    1857. 

  1857. <H5>Parameters</H5>
    1858. 

  1858. <TT>st_netfd_setspecific()</TT> has the following parameters:<P>
    1859. 

  1859. <TT>fd</TT><P>
    1860. 

  1860. A valid file descriptor object identifier (see
    1861. 

  1861. <A HREF=#netfd_t><B>st_netfd_t</B></A>).
    1862. 

  1862. <P>
    1863. 

  1863. <TT>value</TT><P>
    1864. 

  1864. The per-descriptor private data, or more likely, a pointer to the data which
    1865. 

  1865. is being associated with the named file descriptor object.
    1866. 

  1866. <P>
    1867. 

  1867. <TT>destructor</TT><P>
    1868. 

  1868. Specifies an optional destructor function for the private data associated
    1869. 

  1869. with <TT>fd</TT>. This function can be specified as <TT>NULL</TT>.
    1870. 

  1870. If <TT>value</TT> is not <TT>NULL</TT>, then this destructor function will
    1871. 

  1871. be called with <TT>value</TT> as an argument upon freeing the file descriptor
    1872. 

  1872. object (see <A HREF=#netfd_free>st_netfd_free()</A> and
    1873. 

  1873. <A HREF=#netfd_close>st_netfd_close()</A>).
    1874. 

  1874. <P>
    1875. 

  1875. <H5>Returns</H5>
    1876. 

  1876. Nothing.
    1877. 

  1877. <P>
    1878. 

  1878. <H5>Description</H5>
    1879. 

  1879. This function allows to associate any data with the specified file
    1880. 

  1880. descriptor object (network connection). If a non-<TT>NULL</TT> destructor
    1881. 

  1881. function is registered, it will be called at one of two times, as long as
    1882. 

  1882. the associated data is not <TT>NULL</TT>:
    1883. 

  1883. <UL>
    1884. 

  1884. <LI>when private data is replaced by calling
    1885. 

  1885. <TT>st_netfd_setspecific()</TT> again
    1886. 

  1886. <LI>upon freeing the file descriptor object (see
    1887. 

  1887. <A HREF=#netfd_free>st_netfd_free()</A> and
    1888. 

  1888. <A HREF=#netfd_close>st_netfd_close()</A>)
    1889. 

  1889. </UL>
    1890. 

  1890. <P>
    1891. 

  1891. <HR>
    1892. 

  1892. <P>
    1893. 

  1893. <A NAME="netfd_getspecific">
    1894. 

  1894. <H4>st_netfd_getspecific()</H4>
    1895. 

  1895. </A>
    1896. 

  1896. Retrieves the per-descriptor private data.
    1897. 

  1897. <P>
    1898. 

  1898. <H5>Syntax</H5>
    1899. 

  1899. 

  1900. <PRE>
    1901. 

  1901. #include &lt;st.h&gt;
    1902. 

  1902. 

  1903. void *st_netfd_getspecific(st_netfd_t fd);
    1904. 

  1904. </PRE>
    1905. 

  1905. <P>
    1906. 

  1906. <H5>Parameters</H5>
    1907. 

  1907. <TT>st_netfd_getspecific()</TT> has the following parameters:<P>
    1908. 

  1908. <TT>fd</TT><P>
    1909. 

  1909. A valid file descriptor object identifier (see
    1910. 

  1910. <A HREF=#netfd_t><B>st_netfd_t</B></A>).
    1911. 

  1911. <P>
    1912. 

  1912. <H5>Returns</H5>
    1913. 

  1913. The data associated with the named file descriptor object. If no data is
    1914. 

  1914. associated with <TT>fd</TT>, then <TT>NULL</TT> is returned. 
    1915. 

  1915. <P>
    1916. 

  1916. <H5>Description</H5>
    1917. 

  1917. This function allows to retrieve the data that was associated with the
    1918. 

  1918. specified file descriptor object (see
    1919. 

  1919. <A HREF=#netfd_setspecific>st_netfd_setspecific()</A>).
    1920. 

  1920. <P>
    1921. 

  1921. <HR>
    1922. 

  1922. <P>
    1923. 

  1923. <A NAME="netfd_serialize_accept">
    1924. 

  1924. <H4>st_netfd_serialize_accept()</H4>
    1925. 

  1925. </A>
    1926. 

  1926. Serializes all subsequent <TT>accept(3)</TT> calls on a specified file
    1927. 

  1927. descriptor object.
    1928. 

  1928. <P>
    1929. 

  1929. <H5>Syntax</H5>
    1930. 

  1930. 

  1931. <PRE>
    1932. 

  1932. #include &lt;st.h&gt;
    1933. 

  1933. 

  1934. int st_netfd_serialize_accept(st_netfd_t fd);
    1935. 

  1935. </PRE>
    1936. 

  1936. <P>
    1937. 

  1937. <H5>Parameters</H5>
    1938. 

  1938. <TT>st_netfd_serialize_accept()</TT> has the following parameters:<P>
    1939. 

  1939. <TT>fd</TT><P>
    1940. 

  1940. A file descriptor object identifier (see
    1941. 

  1941. <A HREF=#netfd_t><B>st_netfd_t</B></A>) which has been successfully created
    1942. 

  1942. from a valid listening socket by <A HREF=#netfd_open>st_netfd_open()</A> or
    1943. 

  1943. <A HREF=#netfd_open_socket>st_netfd_open_socket()</A>.
    1944. 

  1944. <P>
    1945. 

  1945. <H5>Returns</H5>
    1946. 

  1946. Upon successful completion, a value of <TT>0</TT> is returned.
    1947. 

  1947. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    1948. 

  1948. to indicate the error.
    1949. 

  1949. <P>
    1950. 

  1950. <H5>Description</H5>
    1951. 

  1951. On some platforms (e.g., Solaris 2.5 and possibly other SVR4 implementations)
    1952. 

  1952. <TT>accept(3)</TT> calls from different processes on
    1953. 

  1953. the same listening socket (see <TT>bind(3)</TT>, <TT>listen(3)</TT>) must be
    1954. 

  1954. serialized. This function causes all subsequent <TT>accept(3)</TT> calls
    1955. 

  1955. made by <A HREF=#accept>st_accept()</A> on the specified file descriptor
    1956. 

  1956. object to be serialized.
    1957. 

  1957. <P>
    1958. 

  1958. <TT>st_netfd_serialize_accept()</TT> must be called <I>before</I>
    1959. 

  1959. creating multiple server processes via <TT>fork(2)</TT>. If the application
    1960. 

  1960. does not create multiple processes to accept network connections on
    1961. 

  1961. the same listening socket, there is no need to call this function.
    1962. 

  1962. <P>
    1963. 

  1963. Deciding whether or not to serialize accepts is tricky.  On some
    1964. 

  1964. platforms (IRIX, Linux) it's not needed at all and
    1965. 

  1965. <TT>st_netfd_serialize_accept()</TT> is a no-op.  On other platforms
    1966. 

  1966. it depends on the version of the OS (Solaris 2.6 doesn't need it but
    1967. 

  1967. earlier versions do).  Serializing accepts does incur a slight
    1968. 

  1968. performance penalty so you want to enable it only if necessary.  Read
    1969. 

  1969. your system's manual pages for <tt>accept(2)</tt> and <tt>select(2)</tt>
    1970. 

  1970. to see if accept serialization is necessary on your system.
    1971. 

  1971. <P>
    1972. 

  1972. <TT>st_netfd_serialize_accept()</TT> allocates resources that are
    1973. 

  1973. freed upon freeing of the specified file descriptor object (see
    1974. 

  1974. <A HREF=#netfd_free>st_netfd_free()</A> and
    1975. 

  1975. <A HREF=#netfd_close>st_netfd_close()</A>).
    1976. 

  1976. <P>
    1977. 

  1977. <HR>
    1978. 

  1978. <P>
    1979. 

  1979. <A NAME="netfd_poll">
    1980. 

  1980. <H4>st_netfd_poll()</H4>
    1981. 

  1981. </A>
    1982. 

  1982. Waits for I/O on a single file descriptor object.
    1983. 

  1983. <P>
    1984. 

  1984. <H5>Syntax</H5>
    1985. 

  1985. 

  1986. <PRE>
    1987. 

  1987. #include &lt;st.h&gt;
    1988. 

  1988. 

  1989. int st_netfd_poll(st_netfd_t fd, int how, st_utime_t timeout);
    1990. 

  1990. </PRE>
    1991. 

  1991. <P>
    1992. 

  1992. <H5>Parameters</H5>
    1993. 

  1993. <TT>st_netfd_poll()</TT> has the following parameters:<P>
    1994. 

  1994. <TT>fd</TT><P>
    1995. 

  1995. A file descriptor object identifier (see
    1996. 

  1996. <A HREF=#netfd_t><B>st_netfd_t</B></A>).
    1997. 

  1997. <P>
    1998. 

  1998. <TT>how</TT><P>
    1999. 

  1999. Specifies I/O events of interest. This parameter can be constructed by
    2000. 

  2000. OR-ing any combination of the following event flags which are defined
    2001. 

  2001. in the <TT>poll.h</TT> header file:<P>
    2002. 

  2002. <TABLE BORDER=0>
    2003. 

  2003. <TR><TD><TT>POLLIN</TT></TD><TD><TT>fd</TT> is readable.</TD></TR>
    2004. 

  2004. <TR><TD><TT>POLLOUT</TT></TD><TD><TT>fd</TT> is is writable.</TD></TR>
    2005. 

  2005. <TR><TD><TT>POLLPRI</TT></TD><TD><TT>fd</TT> has an exception condition.</TD>
    2006. 

  2006. </TR>
    2007. 

  2007. </TABLE>
    2008. 

  2008. <P>
    2009. 

  2009. <TT>timeout</TT><P>
    2010. 

  2010. Amount of time in microseconds the call will block waiting for I/O
    2011. 

  2011. to become ready. This parameter is a variable of type
    2012. 

  2012. <A HREF=#utime_t><B>st_utime_t</B></A>. If this time expires without any
    2013. 

  2013. I/O becoming ready, <TT>st_netfd_poll()</TT> returns an error and sets
    2014. 

  2014. <TT>errno</TT> to <TT>ETIME</TT>.
    2015. 

  2015. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2016. 

  2016. last context switch</A>.
    2017. 

  2017. <P>
    2018. 

  2018. <H5>Returns</H5>
    2019. 

  2019. If the named file descriptor object is ready for I/O within the specified
    2020. 

  2020. amount of time, a value of <TT>0</TT> is returned. Otherwise, a value
    2021. 

  2021. of <TT>-1</TT> is returned and <TT>errno</TT> is set to indicate the error:
    2022. 

  2022. <P>
    2023. 

  2023. <TABLE BORDER=0>
    2024. 

  2024. <TR><TD><TT>EBADF</TT></TD><TD>The underlying OS file descriptor is invalid.
    2025. 

  2025. </TD></TR>
    2026. 

  2026. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2027. 

  2027. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2028. 

  2028. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred without any I/O
    2029. 

  2029. becoming ready.</TD></TR>
    2030. 

  2030. </TABLE>
    2031. 

  2031. <P>
    2032. 

  2032. <H5>Description</H5>
    2033. 

  2033. This function returns as soon as I/O is ready on the named file
    2034. 

  2034. descriptor object or the specified amount of time expires. The
    2035. 

  2035. <TT>how</TT> parameter should be set to the I/O events (readable,
    2036. 

  2036. writable, exception, or some combination) that the caller is interested
    2037. 

  2037. in. If the value of <TT>timeout</TT> is <tt>ST_UTIME_NO_TIMEOUT</tt>
    2038. 

  2038. (<TT>-1</TT>), this function blocks until a requested I/O event occurs
    2039. 

  2039. or until the call is interrupted by <A
    2040. 

  2040. HREF=#thread_interrupt>st_thread_interrupt()</A>.<p>
    2041. 

  2041. Despite having an interface like <tt>poll(2)</tt>, this function uses
    2042. 

  2042. the same event notification mechanism as the rest of the library.  For
    2043. 

  2043. instance if an alternative event nofication mechanism was set using <a
    2044. 

  2044. href=#set_eventsys>st_set_eventsys()</a>, this function uses that
    2045. 

  2045. mechanism to check for events.<p>
    2046. 

  2046. <b>Note: </b> if <TT>kqueue(2)</TT> is used as an alternative event
    2047. 

  2047. notification mechanism (see <A
    2048. 

  2048. HREF=#set_eventsys>st_set_eventsys()</A>), the <TT>POLLPRI</TT>
    2049. 

  2049. event flag is not supported and <TT>st_netfd_poll()</TT> will return an error
    2050. 

  2050. if it's set (<TT>errno</TT> will be set to <TT>EINVAL</TT>).
    2051. 

  2051. <P>
    2052. 

  2052. <HR>
    2053. 

  2053. <P>
    2054. 

  2054. <A NAME="accept">
    2055. 

  2055. <H4>st_accept()</H4>
    2056. 

  2056. </A>
    2057. 

  2057. Accepts a connection on a specified file descriptor object.
    2058. 

  2058. <P>
    2059. 

  2059. <H5>Syntax</H5>
    2060. 

  2060. 

  2061. <PRE>
    2062. 

  2062. #include &lt;st.h&gt;
    2063. 

  2063. 

  2064. st_netfd_t st_accept(st_netfd_t fd, struct sockaddr *addr, int *addrlen,
    2065. 

  2065.                      st_utime_t timeout);
    2066. 

  2066. </PRE>
    2067. 

  2067. <P>
    2068. 

  2068. <H5>Parameters</H5>
    2069. 

  2069. <TT>st_accept()</TT> has the following parameters:<P>
    2070. 

  2070. <TT>fd</TT><P>
    2071. 

  2071. A file descriptor object identifier (see
    2072. 

  2072. <A HREF=#netfd_t><B>st_netfd_t</B></A>) representing the rendezvous socket
    2073. 

  2073. on which the caller is willing to accept new connections. This object has been
    2074. 

  2074. created from a valid listening socket by
    2075. 

  2075. <A HREF=#netfd_open>st_netfd_open()</A> or
    2076. 

  2076. <A HREF=#netfd_open_socket>st_netfd_open_socket()</A>.<P>
    2077. 

  2077. <TT>addr</TT><P>
    2078. 

  2078. If this value is non-zero, it is a result parameter that is filled
    2079. 

  2079. in with the address of the connecting entity, as known to the communications
    2080. 

  2080. layer (see <TT>accept(3)</TT>).<P>
    2081. 

  2081. <TT>addrlen</TT><P>
    2082. 

  2082. This parameter should initially contain the amount of space pointed to by
    2083. 

  2083. <TT>addr</TT>; on return it will contain the actual length (in bytes) of the
    2084. 

  2084. address returned (see <TT>accept(3)</TT>).<P>
    2085. 

  2085. <TT>timeout</TT><P>
    2086. 

  2086. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the time
    2087. 

  2087. limit in microseconds for completion of the accept operation.
    2088. 

  2088. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2089. 

  2089. last context switch</A>.
    2090. 

  2090. <P>
    2091. 

  2091. <H5>Returns</H5>
    2092. 

  2092. Upon successful completion, a new file descriptor object identifier
    2093. 

  2093. representing the newly accepted connection is returned. Otherwise,
    2094. 

  2094. <TT>NULL</TT> is returned and <TT>errno</TT> is set to indicate the error.
    2095. 

  2095. Possible <TT>errno</TT> values are the same as set by the <TT>accept(3)</TT>
    2096. 

  2096. call with two exceptions:<P>
    2097. 

  2097. <TABLE BORDER=0>
    2098. 

  2098. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2099. 

  2099. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2100. 

  2100. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred and no pending
    2101. 

  2101. connection was accepted.</TD></TR>
    2102. 

  2102. </TABLE>
    2103. 

  2103. <P>
    2104. 

  2104. <H5>Description</H5>
    2105. 

  2105. This function accepts the first connection from the queue of pending
    2106. 

  2106. connections and creates a new file descriptor object for the newly
    2107. 

  2107. accepted connection. The rendezvous socket can still be used to accept
    2108. 

  2108. more connections.<P>
    2109. 

  2109. <TT>st_accept()</TT> blocks the calling thread until either a new connection
    2110. 

  2110. is successfully accepted or an error occurs. If no pending connection can
    2111. 

  2111. be accepted before the time limit, this function returns <TT>NULL</TT>
    2112. 

  2112. and sets <TT>errno</TT> to <TT>ETIME</TT>.
    2113. 

  2113. <P>
    2114. 

  2114. <HR>
    2115. 

  2115. <P>
    2116. 

  2116. <A NAME="connect">
    2117. 

  2117. <H4>st_connect()</H4>
    2118. 

  2118. </A>
    2119. 

  2119. Initiates a connection on a specified file descriptor object.
    2120. 

  2120. <P>
    2121. 

  2121. <H5>Syntax</H5>
    2122. 

  2122. 

  2123. <PRE>
    2124. 

  2124. #include &lt;st.h&gt;
    2125. 

  2125. 

  2126. int st_connect(st_netfd_t fd, struct sockaddr *addr, int addrlen,
    2127. 

  2127.                st_utime_t timeout);
    2128. 

  2128. </PRE>
    2129. 

  2129. <P>
    2130. 

  2130. <H5>Parameters</H5>
    2131. 

  2131. <TT>st_connect()</TT> has the following parameters:<P>
    2132. 

  2132. <TT>fd</TT><P>
    2133. 

  2133. A file descriptor object identifier (see
    2134. 

  2134. <A HREF=#netfd_t><B>st_netfd_t</B></A>) representing a socket.<P>
    2135. 

  2135. <TT>addr</TT><P>
    2136. 

  2136. A pointer to the address of the peer to which the socket is to be connected.
    2137. 

  2137. <P>
    2138. 

  2138. <TT>addrlen</TT><P>
    2139. 

  2139. This parameter specifies the amount of space pointed to by <TT>addr</TT>.
    2140. 

  2140. <P>
    2141. 

  2141. <TT>timeout</TT><P>
    2142. 

  2142. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the time
    2143. 

  2143. limit in microseconds for completion of the connect operation.
    2144. 

  2144. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2145. 

  2145. last context switch</A>.
    2146. 

  2146. <P>
    2147. 

  2147. <H5>Returns</H5>
    2148. 

  2148. Upon successful completion, a value of <TT>0</TT> is returned.
    2149. 

  2149. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    2150. 

  2150. to indicate the error. Possible <TT>errno</TT> values are the same as set
    2151. 

  2151. by the <TT>connect(3)</TT> call with two exceptions:<P>
    2152. 

  2152. <TABLE BORDER=0>
    2153. 

  2153. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2154. 

  2154. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2155. 

  2155. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred and connection setup
    2156. 

  2156. was not completed.</TD></TR>
    2157. 

  2157. </TABLE> 
    2158. 

  2158. <P>
    2159. 

  2159. <H5>Description</H5>
    2160. 

  2160. This function is usually invoked on a file descriptor object representing
    2161. 

  2161. a TCP socket. Upon completion it establishes a TCP connection to the peer.
    2162. 

  2162. If the underlying OS socket is not bound, it will be bound to an arbitrary
    2163. 

  2163. local address (see <TT>connect(3)</TT>).<P>
    2164. 

  2164. <TT>st_connect()</TT> blocks the calling thread until either the connection
    2165. 

  2165. is successfully established or an error occurs. If the connection setup
    2166. 

  2166. cannot complete before the specified time limit, this function fails with
    2167. 

  2167. <TT>errno</TT> set to <TT>ETIME</TT>.
    2168. 

  2168. <P>
    2169. 

  2169. <HR>
    2170. 

  2170. <P>
    2171. 

  2171. <A NAME="read">
    2172. 

  2172. <H4>st_read()</H4>
    2173. 

  2173. </A>
    2174. 

  2174. Reads data from a specified file descriptor object.
    2175. 

  2175. <P>
    2176. 

  2176. <H5>Syntax</H5>
    2177. 

  2177. 

  2178. <PRE>
    2179. 

  2179. #include &lt;st.h&gt;
    2180. 

  2180. 

  2181. ssize_t st_read(st_netfd_t fd, void *buf, size_t nbyte, st_utime_t timeout);
    2182. 

  2182. </PRE>
    2183. 

  2183. <P>
    2184. 

  2184. <H5>Parameters</H5>
    2185. 

  2185. <TT>st_read()</TT> has the following parameters:<P>
    2186. 

  2186. <TT>fd</TT><P>
    2187. 

  2187. A file descriptor object identifier (see
    2188. 

  2188. <A HREF=#netfd_t><B>st_netfd_t</B></A>).<P>
    2189. 

  2189. <TT>buf</TT><P>
    2190. 

  2190. A pointer to a buffer to hold the data read in. On output the buffer
    2191. 

  2191. contains the data.<P>
    2192. 

  2192. <TT>nbyte</TT><P>
    2193. 

  2193. The size of <TT>buf</TT> in bytes.<P>
    2194. 

  2194. <TT>timeout</TT><P>
    2195. 

  2195. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the time
    2196. 

  2196. limit in microseconds for completion of the read operation.
    2197. 

  2197. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2198. 

  2198. last context switch</A>.
    2199. 

  2199. <P>
    2200. 

  2200. <H5>Returns</H5>
    2201. 

  2201. On success a non-negative integer indicating the number of bytes actually
    2202. 

  2202. read is returned (a value of <TT>0</TT> means the network connection is
    2203. 

  2203. closed or end of file is reached). Otherwise, a value of <TT>-1</TT> is
    2204. 

  2204. returned and <TT>errno</TT> is set to indicate the error.
    2205. 

  2205. Possible <TT>errno</TT> values are the same as set by the <TT>read(2)</TT>
    2206. 

  2206. call with two exceptions:<P>
    2207. 

  2207. <TABLE BORDER=0>
    2208. 

  2208. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2209. 

  2209. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2210. 

  2210. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred and no data was read.
    2211. 

  2211. </TD></TR>
    2212. 

  2212. </TABLE>
    2213. 

  2213. <P>
    2214. 

  2214. <H5>Description</H5>
    2215. 

  2215. This function blocks the calling thread until it encounters an end-of-stream
    2216. 

  2216. indication, some positive number of bytes (but no more than <TT>nbyte</TT>
    2217. 

  2217. bytes) are read in, a timeout occurs, or an error occurs.
    2218. 

  2218. <P>
    2219. 

  2219. <HR>
    2220. 

  2220. <P>
    2221. 

  2221. <A NAME="read_fully">
    2222. 

  2222. <H4>st_read_fully()</H4>
    2223. 

  2223. </A>
    2224. 

  2224. Reads the specified amount of data in full from a file descriptor object.
    2225. 

  2225. <P>
    2226. 

  2226. <H5>Syntax</H5>
    2227. 

  2227. 

  2228. <PRE>
    2229. 

  2229. #include &lt;st.h&gt;
    2230. 

  2230. 

  2231. ssize_t st_read_fully(st_netfd_t fd, void *buf, size_t nbyte,
    2232. 

  2232.                       st_utime_t timeout);
    2233. 

  2233. </PRE>
    2234. 

  2234. <P>
    2235. 

  2235. <H5>Parameters</H5>
    2236. 

  2236. <TT>st_read_fully()</TT> has the following parameters:<P>
    2237. 

  2237. <TT>fd</TT><P>
    2238. 

  2238. A file descriptor object identifier (see
    2239. 

  2239. <A HREF=#netfd_t><B>st_netfd_t</B></A>).<P>
    2240. 

  2240. <TT>buf</TT><P>
    2241. 

  2241. A pointer to a buffer to hold the data read in. On output the buffer
    2242. 

  2242. contains the data.<P>
    2243. 

  2243. <TT>nbyte</TT><P>
    2244. 

  2244. The amount of data to be read in full (in bytes). It must not exceed the
    2245. 

  2245. size of <TT>buf</TT>.<P>
    2246. 

  2246. <TT>timeout</TT><P>
    2247. 

  2247. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the
    2248. 

  2248. inactivity timeout (in microseconds).
    2249. 

  2249. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2250. 

  2250. last context switch</A>.
    2251. 

  2251. <P>
    2252. 

  2252. <H5>Returns</H5>
    2253. 

  2253. On success a non-negative integer indicating the number of bytes actually
    2254. 

  2254. read is returned (a value less than <TT>nbyte</TT> means the network
    2255. 

  2255. connection is closed or end of file is reached). Otherwise, a value of
    2256. 

  2256. <TT>-1</TT> is returned and <TT>errno</TT> is set to indicate the error.
    2257. 

  2257. Possible <TT>errno</TT> values are the same as set by the <TT>read(2)</TT>
    2258. 

  2258. call with two exceptions:<P>
    2259. 

  2259. <TABLE BORDER=0>
    2260. 

  2260. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2261. 

  2261. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2262. 

  2262. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred.
    2263. 

  2263. </TD></TR>
    2264. 

  2264. </TABLE>
    2265. 

  2265. <P>
    2266. 

  2266. <H5>Description</H5>
    2267. 

  2267. This function blocks the calling thread until the specified amount of data
    2268. 

  2268. is read in full, it encounters an end-of-stream indication, a timeout occurs,
    2269. 

  2269. or an error occurs.
    2270. 

  2270. <P>
    2271. 

  2271. <HR>
    2272. 

  2272. <P>
    2273. 

  2273. <A NAME="read_resid">
    2274. 

  2274. <H4>st_read_resid()</H4>
    2275. 

  2275. </A>
    2276. 

  2276. Reads the specified amount of data in full from a file descriptor object.
    2277. 

  2277. <P>
    2278. 

  2278. <H5>Syntax</H5>
    2279. 

  2279. 

  2280. <PRE>
    2281. 

  2281. #include &lt;st.h&gt;
    2282. 

  2282. 

  2283. int st_read_resid(st_netfd_t fd, void *buf, size_t *resid,
    2284. 

  2284. 		  st_utime_t timeout);
    2285. 

  2285. </PRE>
    2286. 

  2286. <P>
    2287. 

  2287. <H5>Parameters</H5>
    2288. 

  2288. <TT>st_read_resid()</TT> has the following parameters:<P>
    2289. 

  2289. <TT>fd</TT><P>
    2290. 

  2290. A file descriptor object identifier (see
    2291. 

  2291. <A HREF=#netfd_t><B>st_netfd_t</B></A>).<P>
    2292. 

  2292. <TT>buf</TT><P>
    2293. 

  2293. A pointer to a buffer to hold the data read in. On output the buffer
    2294. 

  2294. contains the data.<P>
    2295. 

  2295. <TT>resid</TT><P>
    2296. 

  2296. A pointer to a number of bytes.
    2297. 

  2297. On entry, the amount of data to be read in full.
    2298. 

  2298. It must not exceed the size of <TT>buf</TT>.
    2299. 

  2299. On return, the amount of data remaining to be read.
    2300. 

  2300. (A non-zero returned value means some but not all of the data was read.)<P>
    2301. 

  2301. <TT>timeout</TT><P>
    2302. 

  2302. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the
    2303. 

  2303. inactivity timeout (in microseconds).
    2304. 

  2304. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2305. 

  2305. last context switch</A>.
    2306. 

  2306. <P>
    2307. 

  2307. <H5>Returns</H5>
    2308. 

  2308. On success, zero is returned.  <TT>*resid</TT> may be zero, indicating
    2309. 

  2309. a complete read, or non-zero, indicating the network
    2310. 

  2310. connection is closed or end of file is reached.
    2311. 

  2311. <P>
    2312. 

  2312. Otherwise, a value of <TT>-1</TT> is returned, <TT>*resid</TT> is non-zero,
    2313. 

  2313. and <TT>errno</TT> is set to indicate the error.
    2314. 

  2314. Possible <TT>errno</TT> values are the same as set by the <TT>read(2)</TT>
    2315. 

  2315. call with two exceptions:<P>
    2316. 

  2316. <TABLE BORDER=0>
    2317. 

  2317. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2318. 

  2318. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2319. 

  2319. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred.
    2320. 

  2320. </TD></TR>
    2321. 

  2321. </TABLE>
    2322. 

  2322. <P>
    2323. 

  2323. <H5>Description</H5>
    2324. 

  2324. This function blocks the calling thread until the specified amount of data
    2325. 

  2325. is read in full, it encounters an end-of-stream indication, a timeout occurs,
    2326. 

  2326. or an error occurs.  It differs from <TT>st_read_fully()</TT> only in that
    2327. 

  2327. it allows the caller to know how many bytes were transferred before an error
    2328. 

  2328. occurred.
    2329. 

  2329. <P>
    2330. 

  2330. <HR>
    2331. 

  2331. <P>
    2332. 

  2332. <A NAME="readv">
    2333. 

  2333. <H4>st_readv()</H4>
    2334. 

  2334. </A>
    2335. 

  2335. Reads data from a specified file descriptor object into multiple buffers.
    2336. 

  2336. <P>
    2337. 

  2337. <H5>Syntax</H5>
    2338. 

  2338. 

  2339. <PRE>
    2340. 

  2340. #include &lt;st.h&gt;
    2341. 

  2341. 

  2342. ssize_t st_readv(st_netfd_t fd, const struct iovec *iov, int iov_size,
    2343. 

  2343. 		 st_utime_t timeout);
    2344. 

  2344. </PRE>
    2345. 

  2345. <P>
    2346. 

  2346. <H5>Parameters</H5>
    2347. 

  2347. <TT>st_readv()</TT> has the following parameters:<P>
    2348. 

  2348. <TT>fd</TT><P>
    2349. 

  2349. A file descriptor object identifier (see
    2350. 

  2350. <A HREF=#netfd_t><B>st_netfd_t</B></A>).<P>
    2351. 

  2351. <TT>iov</TT><P>
    2352. 

  2352. An array of <tt>iovec</tt> structures that identify the buffers for holding
    2353. 

  2353. the data read in.
    2354. 

  2354. On return the buffers contain the data.<P>
    2355. 

  2355. <TT>iov_size</TT><P>
    2356. 

  2356. The number of <tt>iovec</tt> structures in the <tt>iov</tt> array.<P>
    2357. 

  2357. <TT>timeout</TT><P>
    2358. 

  2358. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the time
    2359. 

  2359. limit in microseconds for completion of the read operation.
    2360. 

  2360. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2361. 

  2361. last context switch</A>.
    2362. 

  2362. <P>
    2363. 

  2363. <H5>Returns</H5>
    2364. 

  2364. On success a non-negative integer indicating the number of bytes actually
    2365. 

  2365. read is returned (a value of <TT>0</TT> means the network connection is
    2366. 

  2366. closed or end of file is reached). Otherwise, a value of <TT>-1</TT> is
    2367. 

  2367. returned and <TT>errno</TT> is set to indicate the error.
    2368. 

  2368. Possible <TT>errno</TT> values are the same as set by the <TT>readv(2)</TT>
    2369. 

  2369. call with two exceptions:<P>
    2370. 

  2370. <TABLE BORDER=0>
    2371. 

  2371. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2372. 

  2372. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2373. 

  2373. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred and no data was read.
    2374. 

  2374. </TD></TR>
    2375. 

  2375. </TABLE>
    2376. 

  2376. <P>
    2377. 

  2377. <H5>Description</H5>
    2378. 

  2378. This function blocks the calling thread until it encounters an end-of-stream
    2379. 

  2379. indication, some positive number of bytes (but no more than fit in the buffers)
    2380. 

  2380. are read in, a timeout occurs, or an error occurs.
    2381. 

  2381. <P>
    2382. 

  2382. <HR>
    2383. 

  2383. <P>
    2384. 

  2384. <A NAME="readv_resid">
    2385. 

  2385. <H4>st_readv_resid()</H4>
    2386. 

  2386. </A>
    2387. 

  2387. Reads the specified amount of data in full from a file descriptor object
    2388. 

  2388. into multiple buffers.
    2389. 

  2389. <P>
    2390. 

  2390. <H5>Syntax</H5>
    2391. 

  2391. 

  2392. <PRE>
    2393. 

  2393. #include &lt;st.h&gt;
    2394. 

  2394. 

  2395. int st_readv_resid(st_netfd_t fd, struct iovec **iov, int *iov_size,
    2396. 

  2396. 		   st_utime_t timeout);
    2397. 

  2397. </PRE>
    2398. 

  2398. <P>
    2399. 

  2399. <H5>Parameters</H5>
    2400. 

  2400. <TT>st_readv_resid()</TT> has the following parameters:<P>
    2401. 

  2401. <TT>fd</TT><P>
    2402. 

  2402. A file descriptor object identifier (see
    2403. 

  2403. <A HREF=#netfd_t><B>st_netfd_t</B></A>).<P>
    2404. 

  2404. <TT>iov</TT><P>
    2405. 

  2405. A pointer to an array of <tt>iovec</tt> structures.
    2406. 

  2406. On entry, the iovecs identify the buffers for holding the data read in.
    2407. 

  2407. On return, the incomplete iovecs.
    2408. 

  2408. This function modifies both the pointer and the array to which it points.<P>
    2409. 

  2409. <TT>iov_size</TT><P>
    2410. 

  2410. A pointer to a number of iovec structures.
    2411. 

  2411. On entry, the number of iovec structures pointed to by <tt>*iov</tt>.
    2412. 

  2412. On return, the number of incomplete or unused iovec structures.
    2413. 

  2413. (A non-zero returned value means some but not all of the data was read.)<P>
    2414. 

  2414. <TT>timeout</TT><P>
    2415. 

  2415. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the
    2416. 

  2416. inactivity timeout (in microseconds).
    2417. 

  2417. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2418. 

  2418. last context switch</A>.
    2419. 

  2419. <P>
    2420. 

  2420. <H5>Returns</H5>
    2421. 

  2421. On success, zero is returned. <TT>*iov_size</TT> may be zero, indicating
    2422. 

  2422. a complete read, or non-zero, indicating the network connection is
    2423. 

  2423. closed or end of file is reached.  <tt>*iov</tt> points to the first
    2424. 

  2424. iovec after the end of the original array on a complete read, or to the
    2425. 

  2425. first incomplete iovec on an incomplete read.
    2426. 

  2426. <P>
    2427. 

  2427. Otherwise, a value of <TT>-1</TT> is returned, <TT>*iov_size</TT> is non-zero,
    2428. 

  2428. and <TT>errno</TT> is set to indicate the error.  <tt>*iov</tt> points to the
    2429. 

  2429. first unused iovec.
    2430. 

  2430. Possible <TT>errno</TT> values are the same as set by the <TT>readv(2)</TT>
    2431. 

  2431. call with two exceptions:<P>
    2432. 

  2432. <TABLE BORDER=0>
    2433. 

  2433. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2434. 

  2434. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2435. 

  2435. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred.
    2436. 

  2436. </TD></TR>
    2437. 

  2437. </TABLE>
    2438. 

  2438. <P>All of the iovecs before <tt>*iov</tt> are modified such that
    2439. 

  2439. <tt>iov_base</tt> points to the end of the original buffer and
    2440. 

  2440. <tt>iov_len</tt> is zero.
    2441. 

  2441. <P>
    2442. 

  2442. <H5>Description</H5>
    2443. 

  2443. This function blocks the calling thread until the specified amount of data
    2444. 

  2444. is read in full, it encounters an end-of-stream indication, a timeout occurs,
    2445. 

  2445. or an error occurs.  Like <tt>st_read_resid()</tt> it blocks the thread until
    2446. 

  2446. <i>all</i> of the requested data is read or an error occurs.  Use
    2447. 

  2447. <tt>st_readv()</tt> to read <i>up to</i> the requested amount of data.
    2448. 

  2448. <P>
    2449. 

  2449. <HR>
    2450. 

  2450. <P>
    2451. 

  2451. <A NAME="write">
    2452. 

  2452. <H4>st_write()</H4>
    2453. 

  2453. </A>
    2454. 

  2454. Writes a buffer of data to a specified file descriptor object.
    2455. 

  2455. <P>
    2456. 

  2456. <H5>Syntax</H5>
    2457. 

  2457. 

  2458. <PRE>
    2459. 

  2459. #include &lt;st.h&gt;
    2460. 

  2460. 

  2461. ssize_t st_write(st_netfd_t fd, const void *buf, size_t nbyte,
    2462. 

  2462.                  st_utime_t timeout);
    2463. 

  2463. </PRE>
    2464. 

  2464. <P>
    2465. 

  2465. <H5>Parameters</H5>
    2466. 

  2466. <TT>st_write()</TT> has the following parameters:<P>
    2467. 

  2467. <TT>fd</TT><P>
    2468. 

  2468. A file descriptor object identifier (see
    2469. 

  2469. <A HREF=#netfd_t><B>st_netfd_t</B></A>).<P>
    2470. 

  2470. <TT>buf</TT><P>
    2471. 

  2471. A pointer to the buffer holding the data to be written.<P>
    2472. 

  2472. <TT>nbyte</TT><P>
    2473. 

  2473. The amount of data in bytes to be written from the buffer.<P>
    2474. 

  2474. <TT>timeout</TT><P>
    2475. 

  2475. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the
    2476. 

  2476. inactivity timeout (in microseconds).
    2477. 

  2477. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2478. 

  2478. last context switch</A>.
    2479. 

  2479. <P>
    2480. 

  2480. <H5>Returns</H5>
    2481. 

  2481. On success a non-negative integer equal to <TT>nbyte</TT> is returned.
    2482. 

  2482. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    2483. 

  2483. to indicate the error. Possible <TT>errno</TT> values are the same as set
    2484. 

  2484. by the <TT>write(2)</TT> call with two exceptions:<P>
    2485. 

  2485. <TABLE BORDER=0>
    2486. 

  2486. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2487. 

  2487. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2488. 

  2488. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred.
    2489. 

  2489. </TD></TR>
    2490. 

  2490. </TABLE> 
    2491. 

  2491. <P>
    2492. 

  2492. <H5>Description</H5>
    2493. 

  2493. This function blocks the calling thread until <I>all</I> the data is written,
    2494. 

  2494. a timeout occurs, or the write operation fails. The return value is equal to
    2495. 

  2495. either <TT>nbyte</TT> (on success) or <TT>-1</TT> (on failure). Note that if
    2496. 

  2496. <TT>st_write()</TT> returns <TT>-1</TT>, some data (less than <TT>nbyte</TT>
    2497. 

  2497. bytes) may have been written before an error occurred.
    2498. 

  2498. <P>
    2499. 

  2499. <HR>
    2500. 

  2500. <P>
    2501. 

  2501. <A NAME="write_resid">
    2502. 

  2502. <H4>st_write_resid()</H4>
    2503. 

  2503. </A>
    2504. 

  2504. Writes a buffer of data to a specified file descriptor object.
    2505. 

  2505. <P>
    2506. 

  2506. <H5>Syntax</H5>
    2507. 

  2507. 

  2508. <PRE>
    2509. 

  2509. #include &lt;st.h&gt;
    2510. 

  2510. 

  2511. int st_write_resid(st_netfd_t fd, const void *buf, size_t *resid,
    2512. 

  2512.                    st_utime_t timeout);
    2513. 

  2513. </PRE>
    2514. 

  2514. <P>
    2515. 

  2515. <H5>Parameters</H5>
    2516. 

  2516. <TT>st_write_resid()</TT> has the following parameters:<P>
    2517. 

  2517. <TT>fd</TT><P>
    2518. 

  2518. A file descriptor object identifier (see
    2519. 

  2519. <A HREF=#netfd_t><B>st_netfd_t</B></A>).<P>
    2520. 

  2520. <TT>buf</TT><P>
    2521. 

  2521. A pointer to the buffer holding the data to be written.<P>
    2522. 

  2522. <TT>resid</TT><P>
    2523. 

  2523. A pointer to a number of bytes.
    2524. 

  2524. On entry, the amount of data to be written from the buffer.
    2525. 

  2525. On return, the amount of data remaining to be written.
    2526. 

  2526. (A non-zero returned value means some but not all of the data was written.)<P>
    2527. 

  2527. <TT>timeout</TT><P>
    2528. 

  2528. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the
    2529. 

  2529. inactivity timeout (in microseconds).
    2530. 

  2530. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2531. 

  2531. last context switch</A>.
    2532. 

  2532. <P>
    2533. 

  2533. <H5>Returns</H5>
    2534. 

  2534. On success, zero is returned and <TT>*resid</TT> is zero.
    2535. 

  2535. Otherwise, a value of <TT>-1</TT> is returned, <TT>*resid</TT> is non-zero,
    2536. 

  2536. and <TT>errno</TT> is set
    2537. 

  2537. to indicate the error. Possible <TT>errno</TT> values are the same as set
    2538. 

  2538. by the <TT>write(2)</TT> call with two exceptions:<P>
    2539. 

  2539. <TABLE BORDER=0>
    2540. 

  2540. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2541. 

  2541. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2542. 

  2542. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred.
    2543. 

  2543. </TD></TR>
    2544. 

  2544. </TABLE> 
    2545. 

  2545. <P>
    2546. 

  2546. <H5>Description</H5>
    2547. 

  2547. This function blocks the calling thread until <I>all</I> the data is written,
    2548. 

  2548. a timeout occurs, or the write operation fails. It differs from
    2549. 

  2549. <TT>st_write()</TT> only in that it allows the caller to know how many bytes
    2550. 

  2550. were transferred before an error occurred.
    2551. 

  2551. <P>
    2552. 

  2552. <HR>
    2553. 

  2553. <P>
    2554. 

  2554. <A NAME="writev">
    2555. 

  2555. <H4>st_writev()</H4>
    2556. 

  2556. </A>
    2557. 

  2557. Writes data to a specified file descriptor object from multiple buffers.
    2558. 

  2558. <P>
    2559. 

  2559. <H5>Syntax</H5>
    2560. 

  2560. 

  2561. <PRE>
    2562. 

  2562. #include &lt;st.h&gt;
    2563. 

  2563. 

  2564. ssize_t st_writev(st_netfd_t fd, const struct iovec *iov, int iov_size,
    2565. 

  2565.                   st_utime_t timeout);
    2566. 

  2566. </PRE>
    2567. 

  2567. <P>
    2568. 

  2568. <H5>Parameters</H5>
    2569. 

  2569. <TT>st_writev()</TT> has the following parameters:<P>
    2570. 

  2570. <TT>fd</TT><P>
    2571. 

  2571. A file descriptor object identifier (see
    2572. 

  2572. <A HREF=#netfd_t><B>st_netfd_t</B></A>).<P>
    2573. 

  2573. <TT>iov</TT><P>
    2574. 

  2574. An array of <TT>iovec</TT> structures that describe the buffers to write
    2575. 

  2575. from (see <TT>writev(2)</TT>).<P>
    2576. 

  2576. <TT>iov_size</TT><P>
    2577. 

  2577. Number of <TT>iovec</TT> structures in the <TT>iov</TT> array.<P>
    2578. 

  2578. <TT>timeout</TT><P>
    2579. 

  2579. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the
    2580. 

  2580. inactivity timeout (in microseconds).
    2581. 

  2581. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2582. 

  2582. last context switch</A>.
    2583. 

  2583. <P>
    2584. 

  2584. <H5>Returns</H5>
    2585. 

  2585. On success a non-negative integer equal to the sum of all the buffer lengths
    2586. 

  2586. is returned. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT>
    2587. 

  2587. is set to indicate the error. Possible <TT>errno</TT> values are the same as
    2588. 

  2588. set by the <TT>writev(2)</TT> call with two exceptions:<P>
    2589. 

  2589. <TABLE BORDER=0>
    2590. 

  2590. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2591. 

  2591. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2592. 

  2592. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred.
    2593. 

  2593. </TD></TR>
    2594. 

  2594. </TABLE>
    2595. 

  2595. <P>
    2596. 

  2596. <H5>Description</H5>
    2597. 

  2597. This function blocks the calling thread until <I>all</I> the data is written,
    2598. 

  2598. a timeout occurs, or the write operation fails. The return value is equal to
    2599. 

  2599. either the sum of all the buffer lengths (on success) or <TT>-1</TT> (on
    2600. 

  2600. failure). Note that if <TT>st_writev()</TT> returns <TT>-1</TT>, part of the
    2601. 

  2601. data may have been written before an error occurred.
    2602. 

  2602. <P>
    2603. 

  2603. <HR>
    2604. 

  2604. <P>
    2605. 

  2605. <A NAME="writev_resid">
    2606. 

  2606. <H4>st_writev_resid()</H4>
    2607. 

  2607. </A>
    2608. 

  2608. Writes multiple buffers of data to a specified file descriptor object.
    2609. 

  2609. <P>
    2610. 

  2610. <H5>Syntax</H5>
    2611. 

  2611. 

  2612. <PRE>
    2613. 

  2613. #include &lt;st.h&gt;
    2614. 

  2614. 

  2615. int st_writev_resid(st_netfd_t fd, struct iovec **iov, int *iov_size,
    2616. 

  2616. 		    st_utime_t timeout);
    2617. 

  2617. </PRE>
    2618. 

  2618. <P>
    2619. 

  2619. <H5>Parameters</H5>
    2620. 

  2620. <TT>st_writev_resid()</TT> has the following parameters:<P>
    2621. 

  2621. <TT>fd</TT><P>
    2622. 

  2622. A file descriptor object identifier (see
    2623. 

  2623. <A HREF=#netfd_t><B>st_netfd_t</B></A>).<P>
    2624. 

  2624. <TT>iov</TT><P>
    2625. 

  2625. A pointer to an array of <tt>iovec</tt> structures.
    2626. 

  2626. On entry, the iovecs identify the buffers holding the data to write.
    2627. 

  2627. On return, the incomplete iovecs.
    2628. 

  2628. This function modifies both the pointer and the array to which it points.<P>
    2629. 

  2629. <TT>iov_size</TT><P>
    2630. 

  2630. A pointer to a number of iovec structures.
    2631. 

  2631. On entry, the number of iovec structures pointed to by <tt>*iov</tt>.
    2632. 

  2632. On return, the number of incomplete or unused iovec structures.
    2633. 

  2633. (A non-zero returned value means some but not all of the data was written.)<P>
    2634. 

  2634. <TT>timeout</TT><P>
    2635. 

  2635. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the
    2636. 

  2636. inactivity timeout (in microseconds).
    2637. 

  2637. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2638. 

  2638. last context switch</A>.
    2639. 

  2639. <P>
    2640. 

  2640. <H5>Returns</H5>
    2641. 

  2641. On success, zero is returned, <TT>*iov_size</TT> is zero, and <tt>*iov</tt>
    2642. 

  2642. points to the first iovec after the end of the original array.
    2643. 

  2643. Otherwise, a value of <TT>-1</TT> is returned, <TT>*iov_size</TT> is non-zero,
    2644. 

  2644. <tt>*iov</tt> points to the first incomplete iovec, and <TT>errno</TT> is set
    2645. 

  2645. to indicate the error. Possible <TT>errno</TT> values are the same as set
    2646. 

  2646. by the <TT>writev(2)</TT> call with two exceptions:<P>
    2647. 

  2647. <TABLE BORDER=0>
    2648. 

  2648. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2649. 

  2649. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2650. 

  2650. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred.
    2651. 

  2651. </TD></TR>
    2652. 

  2652. </TABLE> 
    2653. 

  2653. <P>
    2654. 

  2654. All of the iovecs before <tt>*iov</tt> are modified such that
    2655. 

  2655. <tt>iov_base</tt> points to the end of the original buffer and
    2656. 

  2656. <tt>iov_len</tt> is zero.
    2657. 

  2657. <P>
    2658. 

  2658. <H5>Description</H5>
    2659. 

  2659. This function blocks the calling thread until <I>all</I> the data is written,
    2660. 

  2660. a timeout occurs, or the write operation fails. It differs from
    2661. 

  2661. <TT>st_writev()</TT> only in that it allows the caller to know how many bytes
    2662. 

  2662. were transferred before an error occurred.
    2663. 

  2663. <P>
    2664. 

  2664. <HR>
    2665. 

  2665. <P>
    2666. 

  2666. <A NAME="recvfrom">
    2667. 

  2667. <H4>st_recvfrom()</H4>
    2668. 

  2668. </A>
    2669. 

  2669. Receives bytes from a file descriptor object and stores the sending peer's
    2670. 

  2670. address.
    2671. 

  2671. <P>
    2672. 

  2672. <H5>Syntax</H5>
    2673. 

  2673. 

  2674. <PRE>
    2675. 

  2675. #include &lt;st.h&gt;
    2676. 

  2676. 

  2677. int st_recvfrom(st_netfd_t fd, void *buf, int len, struct sockaddr *from,
    2678. 

  2678.                 int *fromlen, st_utime_t timeout);
    2679. 

  2679. </PRE>
    2680. 

  2680. <P>
    2681. 

  2681. <H5>Parameters</H5>
    2682. 

  2682. <TT>st_recvfrom()</TT> has the following parameters:<P>
    2683. 

  2683. <TT>fd</TT><P>
    2684. 

  2684. A file descriptor object identifier (see
    2685. 

  2685. <A HREF=#netfd_t><B>st_netfd_t</B></A>) representing a UDP socket.<P>
    2686. 

  2686. <TT>buf</TT><P>
    2687. 

  2687. A pointer to a buffer to hold the data received.<P>
    2688. 

  2688. <TT>len</TT><P>
    2689. 

  2689. The size of <TT>buf</TT> in bytes.<P>
    2690. 

  2690. <TT>from</TT><P>
    2691. 

  2691. If this parameter is not a <TT>NULL</TT> pointer, the source address of the
    2692. 

  2692. message is filled in (see <TT>recvfrom(3)</TT>).<P>
    2693. 

  2693. <TT>fromlen</TT><P>
    2694. 

  2694. This is a value-result parameter, initialized to the size of the buffer
    2695. 

  2695. associated with <TT>from</TT>, and modified on return to indicate the actual
    2696. 

  2696. size of the address stored there.<P>
    2697. 

  2697. <TT>timeout</TT><P>
    2698. 

  2698. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the time
    2699. 

  2699. limit in microseconds for completion of the receive operation.
    2700. 

  2700. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2701. 

  2701. last context switch</A>.
    2702. 

  2702. <P>
    2703. 

  2703. <H5>Returns</H5>
    2704. 

  2704. On success a non-negative integer indicating the length of the received
    2705. 

  2705. message in bytes is returned. Otherwise, a value of <TT>-1</TT> is returned
    2706. 

  2706. and <TT>errno</TT> is set to indicate the error. Possible <TT>errno</TT>
    2707. 

  2707. values are the same as set by the <TT>recvfrom(3)</TT> call with two
    2708. 

  2708. exceptions:<P>
    2709. 

  2709. <TABLE BORDER=0>
    2710. 

  2710. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2711. 

  2711. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2712. 

  2712. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred and no data was received.
    2713. 

  2713. </TD></TR>
    2714. 

  2714. </TABLE>
    2715. 

  2715. <P>
    2716. 

  2716. <H5>Description</H5>
    2717. 

  2717. This function receives up to a specified number of bytes from the specified
    2718. 

  2718. file descriptor object representing a UDP socket.<P>
    2719. 

  2719. <TT>st_recvfrom()</TT> blocks the calling thread until one or more bytes are
    2720. 

  2720. transferred, a timeout has occurred, or there is an error. No more than
    2721. 

  2721. <TT>len</TT> bytes will be transferred.
    2722. 

  2722. <P>
    2723. 

  2723. <HR>
    2724. 

  2724. <P>
    2725. 

  2725. <A NAME="sendto">
    2726. 

  2726. <H4>st_sendto()</H4>
    2727. 

  2727. </A>
    2728. 

  2728. Sends bytes to a specified destination.
    2729. 

  2729. <P>
    2730. 

  2730. <H5>Syntax</H5>
    2731. 

  2731. 

  2732. <PRE>
    2733. 

  2733. #include &lt;st.h&gt;
    2734. 

  2734. 

  2735. int st_sendto(st_netfd_t fd, const void *msg, int len, struct sockaddr *to,
    2736. 

  2736.               int tolen, st_utime_t timeout);
    2737. 

  2737. </PRE>
    2738. 

  2738. <P>
    2739. 

  2739. <H5>Parameters</H5>
    2740. 

  2740. <TT>st_sendto()</TT> has the following parameters:<P>
    2741. 

  2741. <TT>fd</TT><P>
    2742. 

  2742. A file descriptor object identifier (see
    2743. 

  2743. <A HREF=#netfd_t><B>st_netfd_t</B></A>) representing a UDP socket.<P>
    2744. 

  2744. <TT>msg</TT><P>
    2745. 

  2745. A pointer to a buffer containing the message to be sent.<P>
    2746. 

  2746. <TT>len</TT><P>
    2747. 

  2747. The length of the message to be sent (in bytes).<P>
    2748. 

  2748. <TT>to</TT><P>
    2749. 

  2749. A pointer to the address of the destination (see <TT>sendto(3)</TT>).<P>
    2750. 

  2750. <TT>tolen</TT><P>
    2751. 

  2751. This parameter specifies the size of the destination address.<P>
    2752. 

  2752. <TT>timeout</TT><P>
    2753. 

  2753. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the time
    2754. 

  2754. limit in microseconds for completion of the send operation.
    2755. 

  2755. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2756. 

  2756. last context switch</A>.
    2757. 

  2757. <P>
    2758. 

  2758. <H5>Returns</H5>
    2759. 

  2759. On success a non-negative integer indicating the number of bytes sent is
    2760. 

  2760. returned. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is
    2761. 

  2761. set to indicate the error. Possible <TT>errno</TT> values are the same as
    2762. 

  2762. set by the <TT>sendto(3)</TT> call with two exceptions:<P>
    2763. 

  2763. <TABLE BORDER=0>
    2764. 

  2764. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2765. 

  2765. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2766. 

  2766. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred and no data was sent.
    2767. 

  2767. </TD></TR>
    2768. 

  2768. </TABLE>
    2769. 

  2769. <P>
    2770. 

  2770. <H5>Description</H5>
    2771. 

  2771. This function sends a specified number of bytes from a file descriptor
    2772. 

  2772. object representing a UDP socket to the specified destination address.
    2773. 

  2773. If no buffer space is available at the underlying OS socket to hold the
    2774. 

  2774. message to be transmitted, then <TT>st_sendto()</TT> blocks the calling
    2775. 

  2775. thread until the space becomes available, a timeout occurs, or an error
    2776. 

  2776. occurs.
    2777. 

  2777. <P>
    2778. 

  2778. <HR>
    2779. 

  2779. <P>
    2780. 

  2780. <A NAME="recvmsg">
    2781. 

  2781. <H4>st_recvmsg()</H4>
    2782. 

  2782. </A>
    2783. 

  2783. Receives a message from a file descriptor object.
    2784. 

  2784. <P>
    2785. 

  2785. <H5>Syntax</H5>
    2786. 

  2786. 

  2787. <PRE>
    2788. 

  2788. #include &lt;st.h&gt;
    2789. 

  2789. 

  2790. int st_recvmsg(st_netfd_t fd, struct msghdr *msg, int flags,
    2791. 

  2791.                st_utime_t timeout);
    2792. 

  2792. </PRE>
    2793. 

  2793. <P>
    2794. 

  2794. <H5>Parameters</H5>
    2795. 

  2795. <TT>st_recvmsg()</TT> has the following parameters:<P>
    2796. 

  2796. <TT>fd</TT><P>
    2797. 

  2797. A file descriptor object identifier (see
    2798. 

  2798. <A HREF=#netfd_t><B>st_netfd_t</B></A>) representing a UDP socket.<P>
    2799. 

  2799. <TT>msg</TT><P>
    2800. 

  2800. A pointer to a <TT>msghdr</TT> structure to describe the data received.<P>
    2801. 

  2801. <TT>flags</TT><P>
    2802. 

  2802. Control flags for <TT>recvmsg(3)</TT>.<P>
    2803. 

  2803. <TT>timeout</TT><P>
    2804. 

  2804. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the time
    2805. 

  2805. limit in microseconds for completion of the receive operation.
    2806. 

  2806. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2807. 

  2807. last context switch</A>.
    2808. 

  2808. <P>
    2809. 

  2809. <H5>Returns</H5>
    2810. 

  2810. On success a non-negative integer indicating the number of bytes received
    2811. 

  2811. is returned. Otherwise, a value of <TT>-1</TT> is returned
    2812. 

  2812. and <TT>errno</TT> is set to indicate the error. Possible <TT>errno</TT>
    2813. 

  2813. values are the same as set by the <TT>recvmsg(3)</TT> call with two
    2814. 

  2814. exceptions:<P>
    2815. 

  2815. <TABLE BORDER=0>
    2816. 

  2816. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2817. 

  2817. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2818. 

  2818. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred and no data was received.
    2819. 

  2819. </TD></TR>
    2820. 

  2820. </TABLE>
    2821. 

  2821. <P>
    2822. 

  2822. <H5>Description</H5>
    2823. 

  2823. This function receives bytes from the specified file descriptor object
    2824. 

  2824. representing a UDP socket.  The operation is controlled by the in/out
    2825. 

  2825. <TT>msg</TT> parameter.<P>
    2826. 

  2826. <TT>st_recvmsg()</TT> blocks the calling thread until one or more bytes are
    2827. 

  2827. transferred, a timeout has occurred, or there is an error.
    2828. 

  2828. <P>
    2829. 

  2829. <HR>
    2830. 

  2830. <P>
    2831. 

  2831. <A NAME="sendmsg">
    2832. 

  2832. <H4>st_sendmsg()</H4>
    2833. 

  2833. </A>
    2834. 

  2834. Sends a message to a file descriptor object.
    2835. 

  2835. <P>
    2836. 

  2836. <H5>Syntax</H5>
    2837. 

  2837. 

  2838. <PRE>
    2839. 

  2839. #include &lt;st.h&gt;
    2840. 

  2840. 

  2841. int st_sendmsg(st_netfd_t fd, const struct msghdr *msg, int flags,
    2842. 

  2842.                st_utime_t timeout);
    2843. 

  2843. </PRE>
    2844. 

  2844. <P>
    2845. 

  2845. <H5>Parameters</H5>
    2846. 

  2846. <TT>st_sendmsg()</TT> has the following parameters:<P>
    2847. 

  2847. <TT>fd</TT><P>
    2848. 

  2848. A file descriptor object identifier (see
    2849. 

  2849. <A HREF=#netfd_t><B>st_netfd_t</B></A>) representing a UDP socket.<P>
    2850. 

  2850. <TT>msg</TT><P>
    2851. 

  2851. A pointer to a <TT>msghdr</TT> structure describing the message to be sent.<P>
    2852. 

  2852. <TT>flags</TT><P>
    2853. 

  2853. Control flags for <TT>sendmsg(3)</TT>.<P>
    2854. 

  2854. <TT>timeout</TT><P>
    2855. 

  2855. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the time
    2856. 

  2856. limit in microseconds for completion of the send operation.
    2857. 

  2857. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2858. 

  2858. last context switch</A>.
    2859. 

  2859. <P>
    2860. 

  2860. <H5>Returns</H5>
    2861. 

  2861. On success a non-negative integer indicating the number of bytes sent is
    2862. 

  2862. returned. Otherwise, a value of <TT>-1</TT> is returned and <TT>errno</TT> is
    2863. 

  2863. set to indicate the error. Possible <TT>errno</TT> values are the same as
    2864. 

  2864. set by the <TT>sendmsg(3)</TT> call with two exceptions:<P>
    2865. 

  2865. <TABLE BORDER=0>
    2866. 

  2866. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2867. 

  2867. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2868. 

  2868. <TR><TD><TT>ETIME</TT></TD><TD>The timeout occurred and no data was sent.
    2869. 

  2869. </TD></TR>
    2870. 

  2870. </TABLE>
    2871. 

  2871. <P>
    2872. 

  2872. <H5>Description</H5>
    2873. 

  2873. This function sends bytes to a file descriptor object representing a UDP
    2874. 

  2874. socket.  The operation is controlled by the <TT>msg</TT> parameter.
    2875. 

  2875. If no buffer space is available at the underlying OS socket to hold the
    2876. 

  2876. message to be transmitted, then <TT>st_sendmsg()</TT> blocks the calling
    2877. 

  2877. thread until the space becomes available, a timeout occurs, or an error
    2878. 

  2878. occurs.
    2879. 

  2879. <P>
    2880. 

  2880. <HR>
    2881. 

  2881. <P>
    2882. 

  2882. <A NAME="open">
    2883. 

  2883. <H4>st_open()</H4>
    2884. 

  2884. </A>
    2885. 

  2885. Opens a file for reading, writing, or both.
    2886. 

  2886. <P>
    2887. 

  2887. <H5>Syntax</H5>
    2888. 

  2888. 

  2889. <PRE>
    2890. 

  2890. #include &lt;st.h&gt;
    2891. 

  2891. 

  2892. st_netfd_t st_open(const char *path, int oflags, mode_t mode);
    2893. 

  2893. </PRE>
    2894. 

  2894. <P>
    2895. 

  2895. <H5>Parameters</H5>
    2896. 

  2896. <TT>st_open()</TT> has the following parameters:<P>
    2897. 

  2897. <TT>path</TT><P>
    2898. 

  2898. The pathname of the file to be opened.<P>
    2899. 

  2899. <TT>oflags</TT><P>
    2900. 

  2900. File status flags. These are the same flags that are used by the
    2901. 

  2901. <TT>open(2)</TT> system call.<P>
    2902. 

  2902. <TT>mode</TT><P>
    2903. 

  2903. Access permission bits of the file mode, if the file is created when
    2904. 

  2904. <TT>O_CREAT</TT> is set in <TT>oflags</TT> (see <TT>open(2)</TT>).
    2905. 

  2905. <P>
    2906. 

  2906. <H5>Returns</H5>
    2907. 

  2907. Upon successful completion, a new file descriptor object identifier is
    2908. 

  2908. returned. Otherwise, <TT>NULL</TT> is returned and <TT>errno</TT> is set
    2909. 

  2909. to indicate the error.
    2910. 

  2910. <P>
    2911. 

  2911. <H5>Description</H5>
    2912. 

  2912. This function creates a new file descriptor object of type
    2913. 

  2913. <A HREF=#netfd_t><B>st_netfd_t</B></A> for the file with the pathname
    2914. 

  2914. <TT>path</TT>. This object can be freed by
    2915. 

  2915. <A HREF=#netfd_free>st_netfd_free()</A> or
    2916. 

  2916. <A HREF=#netfd_close>st_netfd_close()</A>.<P>
    2917. 

  2917. The primary purpose of this function is to open FIFOs (named pipes) or
    2918. 

  2918. other special files in order to create an end point of communication.
    2919. 

  2919. However, it can be used on regular files as well.<P>
    2920. 

  2920. Among other things, this function always sets a non-blocking flag on the
    2921. 

  2921. underlying OS file descriptor, so there is no need to include that flag in
    2922. 

  2922. <TT>oflags</TT>.
    2923. 

  2923. <P>
    2924. 

  2924. <HR>
    2925. 

  2925. <P>
    2926. 

  2926. <A NAME="poll">
    2927. 

  2927. <H4>st_poll()</H4>
    2928. 

  2928. </A>
    2929. 

  2929. Detects when I/O is ready for a set of OS file descriptors.
    2930. 

  2930. <P>
    2931. 

  2931. <H5>Syntax</H5>
    2932. 

  2932. 

  2933. <PRE>
    2934. 

  2934. #include &lt;st.h&gt;
    2935. 

  2935. 

  2936. int st_poll(struct pollfd *pds, int npds, st_utime_t timeout);
    2937. 

  2937. </PRE>
    2938. 

  2938. <P>
    2939. 

  2939. <H5>Parameters</H5>
    2940. 

  2940. <TT>st_poll()</TT> has the following parameters:<P>
    2941. 

  2941. <TT>pds</TT><P>
    2942. 

  2942. A pointer to an array of <TT>pollfd</TT> structures (see <TT>poll(2)</TT>).
    2943. 

  2943. <P>
    2944. 

  2944. <TT>npds</TT><P>
    2945. 

  2945. The number of elements in the <TT>pds</TT> array.<P>
    2946. 

  2946. <TT>timeout</TT><P>
    2947. 

  2947. A value of type <A HREF=#utime_t><B>st_utime_t</B></A> specifying the
    2948. 

  2948. amount of time in <I>microseconds</I> the call will block waiting for I/O
    2949. 

  2949. to become ready. If this time expires without any I/O becoming ready,
    2950. 

  2950. <TT>st_poll()</TT> returns zero.
    2951. 

  2951. Note that timeouts are measured <A HREF="notes.html#timeouts">since the
    2952. 

  2952. last context switch</A>.
    2953. 

  2953. <P>
    2954. 

  2954. <H5>Returns</H5>
    2955. 

  2955. Upon successful completion, a non-negative value is returned. A positive
    2956. 

  2956. value indicates the total number of OS file descriptors in <TT>pds</TT>
    2957. 

  2957. that have events. A value of <TT>0</TT> indicates that the call timed out.
    2958. 

  2958. Upon failure, a value of <TT>-1</TT> is returned and <TT>errno</TT> is set
    2959. 

  2959. to indicate the error:<P>
    2960. 

  2960. <TABLE BORDER=0>
    2961. 

  2961. <TR><TD><TT>EINTR</TT></TD><TD>The current thread was interrupted by
    2962. 

  2962. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.</TD></TR>
    2963. 

  2963. </TABLE>
    2964. 

  2964. <P>
    2965. 

  2965. If an alternative event notification mechanism has been set by
    2966. 

  2966. <A HREF=#set_eventsys>st_set_eventsys()</A>, other values of
    2967. 

  2967. <TT>errno</TT> could be set upon failure as well.  The values
    2968. 

  2968. depend on the specific mechanism in use.
    2969. 

  2969. <P>
    2970. 

  2970. <H5>Description</H5>
    2971. 

  2971. This function returns as soon as I/O is ready on one or more of the specified
    2972. 

  2972. OS file descriptors. A count of the number of ready descriptors is returned
    2973. 

  2973. unless a timeout occurs, in which case zero is returned.<P>
    2974. 

  2974. The <TT>pollfd</TT> structure is defined in the <TT>poll.h</TT> header file
    2975. 

  2975. and contains the following members:<P>
    2976. 

  2976. <PRE>
    2977. 

  2977.     int fd;             /* OS file descriptor */
    2978. 

  2978.     short events;       /* requested events   */
    2979. 

  2979.     short revents;      /* returned events    */
    2980. 

  2980. </PRE>
    2981. 

  2981. The <TT>events</TT> field should be set to the I/O events (readable,
    2982. 

  2982. writable, exception, or some combination) that the caller is interested in.
    2983. 

  2983. On return, the <TT>revents</TT> field is set to indicate what kind of I/O
    2984. 

  2984. is ready on the respective descriptor.<P>
    2985. 

  2985. The <TT>events</TT> and <TT>revents</TT> fields are constructed by OR-ing
    2986. 

  2986. any combination of the following event flags (defined in <TT>poll.h</TT>):
    2987. 

  2987. <P>
    2988. 

  2988. <TABLE BORDER=0>
    2989. 

  2989. <TR><TD><TT>POLLIN</TT></TD><TD><TT>fd</TT> is readable.</TD></TR>
    2990. 

  2990. <TR><TD><TT>POLLOUT</TT></TD><TD><TT>fd</TT> is is writable.</TD></TR>
    2991. 

  2991. <TR><TD><TT>POLLPRI</TT></TD><TD><TT>fd</TT> has an exception condition.</TD>
    2992. 

  2992. </TR>
    2993. 

  2993. <TR><TD><TT>POLLNVAL</TT></TD><TD><TT>fd</TT> is bad.</TD></TR>
    2994. 

  2994. </TABLE>
    2995. 

  2995. <P>
    2996. 

  2996. The <TT>POLLNVAL</TT> flag is only valid in the <TT>revents</TT> field;
    2997. 

  2997. it is not used in the <TT>events</TT> field.<P>
    2998. 

  2998. Despite having an interface like <tt>poll(2)</tt>, this function uses
    2999. 

  2999. the same event notification mechanism as the rest of the library.  For
    3000. 

  3000. instance if an alternative event nofication mechanism was set using <a
    3001. 

  3001. href=#set_eventsys>st_set_eventsys()</a>, this function uses that
    3002. 

  3002. mechanism to check for events.<p>
    3003. 

  3003. Note that unlike the <TT>poll(2)</TT> call, this function has the
    3004. 

  3004. <TT>timeout</TT> parameter expressed in microseconds. If the value of
    3005. 

  3005. <TT>timeout</TT> is <tt>ST_UTIME_NO_TIMEOUT</tt>
    3006. 

  3006. (<TT>-1</TT>), this function blocks until a requested I/O
    3007. 

  3007. event occurs or until the call is interrupted by
    3008. 

  3008. <A HREF=#thread_interrupt>st_thread_interrupt()</A>.
    3009. 

  3009. <P>
    3010. 

  3010. <b>Note: </b> if <TT>kqueue(2)</TT> is used as an alternative event
    3011. 

  3011. notification mechanism (see <A
    3012. 

  3012. HREF=#set_eventsys>st_set_eventsys()</A>), the <TT>POLLPRI</TT>
    3013. 

  3013. event flag is not supported and <TT>st_poll()</TT> will return an error
    3014. 

  3014. if it's set (<TT>errno</TT> will be set to <TT>EINVAL</TT>).
    3015. 

  3015. <P>
    3016. 

  3016. <HR>
    3017. 

  3017. <P>
    3018. 

  3018. 

  3019. <A NAME="progr">
    3020. 

  3020. <H2>Program Structure</H2>
    3021. 

  3021. </A>
    3022. 

  3022. <P>
    3023. 

  3023. Generally, the following steps should be followed when writing an application
    3024. 

  3024. using the State Threads library:
    3025. 

  3025. <P>
    3026. 

  3026. <OL>
    3027. 

  3027. <LI>Configure the library by calling these pre-init functions, if desired.
    3028. 

  3028.   <ul>
    3029. 

  3029.   <li><A HREF="#set_utime_function">st_set_utime_function()</A></li>
    3030. 

  3030.   <li><A HREF="#set_eventsys">st_set_eventsys()</A></li>
    3031. 

  3031.   </ul>
    3032. 

  3032.   </LI>
    3033. 

  3033. <P>
    3034. 

  3034. <LI>Initialize the library by calling <A HREF=#st_init>st_init()</A>.</LI>
    3035. 

  3035. <P>
    3036. 

  3036. <LI>Configure the library by calling these post-init functions, if desired.
    3037. 

  3037.   <ul>
    3038. 

  3038.   <li><A HREF="#timecache_set">st_timecache_set()</A></li>
    3039. 

  3039.   <li><A HREF="#randomize_stacks">st_randomize_stacks()</A></li>
    3040. 

  3040.   <li><A HREF="#set_switch_in_cb">st_set_switch_in_cb()</A></li>
    3041. 

  3041.   <li><A HREF="#set_switch_out_cb">st_set_switch_out_cb()</A></li>
    3042. 

  3042.   </ul>
    3043. 

  3043.   </LI>
    3044. 

  3044. <P>
    3045. 

  3045. <LI>Create resources that will be shared among different processes:
    3046. 

  3046.     create and bind listening sockets (see <TT>socket(3)</TT>,
    3047. 

  3047.     <TT>bind(3)</TT>, <TT>listen(3)</TT>,
    3048. 

  3048.     <A HREF=#netfd_open_socket>st_netfd_open_socket()</A>, and possibly
    3049. 

  3049.     <A HREF=#netfd_serialize_accept>st_netfd_serialize_accept()</A>),
    3050. 

  3050.     create shared memory segments, inter-process communication (IPC)
    3051. 

  3051.     channels and synchronization primitives (if any).</LI>
    3052. 

  3052. <P>
    3053. 

  3053. <LI>Create several processes via <TT>fork(2)</TT>. The parent process should
    3054. 

  3054.     either exit or become a "watchdog" (e.g., it starts a new process when
    3055. 

  3055.     an existing one crashes, does a cleanup upon application termination,
    3056. 

  3056.     etc.).</LI>
    3057. 

  3057. <P>
    3058. 

  3058. <LI>In each child process create a pool of threads (see
    3059. 

  3059.     <A HREF=#thread_create>st_thread_create()</A>) to handle user
    3060. 

  3060.     connections. Each thread in the pool may accept client connections
    3061. 

  3061.     (<A HREF=#accept>st_accept()</A>), connect to other servers
    3062. 

  3062.     (<A HREF=#connect>st_connect()</A>), perform various network I/O
    3063. 

  3063.     (<A HREF=#read>st_read()</A>, <A HREF=#write>st_write()</A>, etc.).</LI>
    3064. 

  3064. </OL>
    3065. 

  3065. <P>
    3066. 

  3066. Note that only State Threads library <A HREF=#io>I/O functions</A> should
    3067. 

  3067. be used for a network I/O: any other I/O calls may block the calling process
    3068. 

  3068. indefinitely. For example, standard I/O functions (<TT>fgets(3)</TT>,
    3069. 

  3069. <TT>fread(3)</TT>, <TT>fwrite(3)</TT>, <TT>fprintf(3)</TT>, etc.) call
    3070. 

  3070. <TT>read(2)</TT> and <TT>write(2)</TT> directly and therefore should not be
    3071. 

  3071. used on sockets or pipes.
    3072. 

  3072. <P>
    3073. 

  3073. Also note that for short <A
    3074. 

  3074. HREF="notes.html#timeouts">timeouts</A> to work the program
    3075. 

  3075. should do context switches (for example by calling
    3076. 

  3076. <TT>st_usleep()</TT>) on a regular basis.
    3077. 

  3077. <P>
    3078. 

  3078. <HR>
    3079. 

  3079. <P>
    3080. 

  3080. 

  3081. <A NAME="block">
    3082. 

  3082. <H2>List of Blocking Functions</H2>
    3083. 

  3083. </A>
    3084. 

  3084. <P>
    3085. 

  3085. The thread context switch (process state change) can <I>only</I> happen
    3086. 

  3086. in a well-known set of blocking functions.
    3087. 

  3087. Only the following functions can block the calling thread:
    3088. 

  3088. <P>
    3089. 

  3089. <DL>
    3090. 

  3090. <DD><A HREF=#thread_join>st_thread_join()</A></DD>
    3091. 

  3091. <DD><A HREF=#sleep>st_sleep()</A></DD>
    3092. 

  3092. <DD><A HREF=#sleep>st_usleep()</A></DD>
    3093. 

  3093. <DD><A HREF=#cond_wait>st_cond_wait()</A></DD>
    3094. 

  3094. <DD><A HREF=#cond_timedwait>st_cond_timedwait()</A></DD>
    3095. 

  3095. <DD><A HREF=#mutex_lock>st_mutex_lock()</A></DD>
    3096. 

  3096. <DD><A HREF=#netfd_poll>st_netfd_poll()</A></DD>
    3097. 

  3097. <DD><A HREF=#accept>st_accept()</A></DD>
    3098. 

  3098. <DD><A HREF=#connect>st_connect()</A></DD>
    3099. 

  3099. <DD><A HREF=#read>st_read()</A></DD>
    3100. 

  3100. <DD><A HREF=#read_fully>st_read_fully()</A></DD>
    3101. 

  3101. <DD><A HREF=#read_resid>st_read_resid()</A></DD>
    3102. 

  3102. <DD><A HREF=#readv>st_readv()</A></DD>
    3103. 

  3103. <DD><A HREF=#readv_resid>st_readv_resid()</A></DD>
    3104. 

  3104. <DD><A HREF=#write>st_write()</A></DD>
    3105. 

  3105. <DD><A HREF=#write_resid>st_write_resid()</A></DD>
    3106. 

  3106. <DD><A HREF=#writev>st_writev()</A></DD>
    3107. 

  3107. <DD><A HREF=#writev_resid>st_writev_resid()</A></DD>
    3108. 

  3108. <DD><A HREF=#recvfrom>st_recvfrom()</A></DD>
    3109. 

  3109. <DD><A HREF=#sendto>st_sendto()</A></DD>
    3110. 

  3110. <DD><A HREF=#recvmsg>st_recvmsg()</A></DD>
    3111. 

  3111. <DD><A HREF=#sendmsg>st_sendmsg()</A></DD>
    3112. 

  3112. <DD><A HREF=#poll>st_poll()</A></DD>
    3113. 

  3113. </DL>
    3114. 

  3114. <P>
    3115. 

  3115. <HR>
    3116. 

  3116. <P>
    3117. 

  3117. 

  3118. </BODY>
    3119. 

  3119. </HTML>
    3120. 

  3120.