home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / catD / allocb.z / allocb
Encoding:
Text File  |  2002-10-03  |  11.3 KB  |  223 lines
  1.  
  2.  
  3.  
  4. aaaallllllllooooccccbbbb((((DDDD3333))))                                                          aaaallllllllooooccccbbbb((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _aaaa_llll_llll_oooo_cccc_bbbb - allocate a message block
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_tttt_yyyy_pppp_eeee_ssss_...._hhhh_>>>>
  13.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_ssss_tttt_rrrr_eeee_aaaa_mmmm_...._hhhh_>>>>
  14.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_ssss_yyyy_ssss_////_dddd_dddd_iiii_...._hhhh_>>>>
  15.      _mmmm_bbbb_llll_kkkk______tttt _****_aaaa_llll_llll_oooo_cccc_bbbb_((((_iiii_nnnn_tttt _s_i_z_e_,,,, _uuuu_iiii_nnnn_tttt______tttt _p_r_i_))))_;;;;
  16.  
  17.    AAAArrrrgggguuuummmmeeeennnnttttssss
  18.      _s_i_z_e      The number of bytes in the message block.
  19.  
  20.      _p_r_i       Priority of the request.
  21.  
  22. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  23.      _aaaa_llll_llll_oooo_cccc_bbbb tries to allocate a STREAMS message block.
  24.  
  25.    RRRReeeettttuuuurrrrnnnn VVVVaaaalllluuuueeeessss
  26.      If successful, _aaaa_llll_llll_oooo_cccc_bbbb returns a pointer to the allocated message block of
  27.      type _MMMM______DDDD_AAAA_TTTT_AAAA (defined in _ssss_yyyy_ssss_////_ssss_tttt_rrrr_eeee_aaaa_mmmm_...._hhhh).  If a block cannot be allocated, a
  28.      _NNNN_UUUU_LLLL_LLLL pointer is returned.
  29.  
  30. UUUUSSSSAAAAGGGGEEEE
  31.      Buffer allocation fails only when the system is out of memory.  If no
  32.      buffer is available, the _bbbb_uuuu_ffff_cccc_aaaa_llll_llll(D3) function can help a module recover
  33.      from an allocation failure.
  34.  
  35.      The psi argument is no longer used, but is retained for compatibility.
  36.  
  37.      The following figure identifies the data structure members that are
  38.      affected when a message block is allocated.
  39.      ||||
  40.      ________
  41.              ||||
  42.      ________
  43.            ______
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.            __
  53.  
  54.            __
  56.  
  57.  
  58.                 |||
  59.       _bbbb______cccc_oooo_nnnn_tttt _((((_0000_))))
  60.       _bbbb______rrrr_pppp_tttt_rrrr
  61.       _bbbb______wwww_pppp_tttt_rrrr
  62.       _bbbb______dddd_aaaa_tttt_aaaa_pppp
  63.    message block
  64.      (_mmmm_bbbb_llll_kkkk______tttt)
  65.                   data block
  66.                    (_dddd_bbbb_llll_kkkk______tttt)
  67.                                 data buffer
  68.                         ______
  70.  
  71.  
  73.                         ______
  75.  
  77.  
  78.  
  79.  
  81.  
  82.  
  83.  
  84.                  ||||
  85.                  ____________
  86.                              ||||
  87.                  ____________
  88.                                  ||||
  89.                                  ______
  90.                                         ||||
  91.                                   ______
  92.                                  .
  93.                                   .
  94.                                   .
  95.                                    .
  96.                                    .
  97.                                    .
  98.                                     .
  99.                                     .
  100.                                      .
  101.                                      .
  102.                                      .
  103.                                       .
  104.                                       .
  105.                                        .
  106.                                        .
  107.                                        .
  108.                                         .
  109.                                  .
  110.                                   .
  111.                                   .
  112.                                    .
  113.                                    .
  114.                                    .
  115.                                     .
  116.                                     .
  117.                                      .
  118.                                      .
  119.                                      .
  120.                                       .
  121.                                       .
  122.                                        .
  123.                                        .
  124.                                        .
  125.                                         .
  126.                 _____________________
  127.                                      ||
  129.  
  130.                   _dddd_bbbb______bbbb_aaaa_ssss_eeee
  131.                   _dddd_bbbb______llll_iiii_mmmm
  132.                   _dddd_bbbb______tttt_yyyy_pppp_eeee _((((_MMMM______DDDD_AAAA_TTTT_AAAA_))))
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.    LLLLeeeevvvveeeellll
  143.      Base or Interrupt.
  144.  
  145.    SSSSyyyynnnncccchhhhrrrroooonnnniiiizzzzaaaattttiiiioooonnnn CCCCoooonnnnssssttttrrrraaaaiiiinnnnttttssss
  146.      Does not sleep.
  147.  
  148.      Driver-defined basic locks, read/write locks, and sleep locks may be held
  149.      across calls to this function.
  150.  
  152.  
  153.  
  154.                                                                         PPPPaaaaggggeeee 1111
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161. aaaallllllllooooccccbbbb((((DDDD3333))))                                                          aaaallllllllooooccccbbbb((((DDDD3333))))
  162.  
  163.  
  164.  
  165.    EEEExxxxaaaammmmpppplllleeee
  166.      Given a pointer to a queue (_q) and an error number (_e_r_r), the _ssss_eeee_nnnn_dddd______eeee_rrrr_rrrr_oooo_rrrr
  167.      routine sends an _MMMM______EEEE_RRRR_RRRR_OOOO_RRRR type message to the stream head.
  168.  
  169.      If a message cannot be allocated, 0 is returned, indicating an allocation
  170.      failure (line 8).  Otherwise, the message type is set to _MMMM______EEEE_RRRR_RRRR_OOOO_RRRR (line
  171.      9).  Line 10 increments the write pointer (_bbbb_pppp_----_>>>>_bbbb______wwww_pppp_tttt_rrrr) by the size (one
  172.      byte) of the data in the message.
  173.  
  174.      A message must be sent up the read side of the stream to arrive at the
  175.      stream head.  To determine whether _q points to a read queue or a write
  176.      queue, the _qqqq_----_>>>>_qqqq______ffff_llll_aaaa_gggg member is tested to see if _QQQQ_RRRR_EEEE_AAAA_DDDD_RRRR is set (line 12).
  177.      If it is not set, _q points to a write queue, and on line 13 the _RRRR_DDDD(D3)
  178.      function is used to find the corresponding read queue.  In line 14, the
  179.      _pppp_uuuu_tttt_nnnn_eeee_xxxx_tttt(D3) function is used to send the message upstream.  Then
  180.      _ssss_eeee_nnnn_dddd______eeee_rrrr_rrrr_oooo_rrrr returns 1 indicating success.
  181.  
  182.       _1111  _ssss_eeee_nnnn_dddd______eeee_rrrr_rrrr_oooo_rrrr_((((_qqqq_,,,, _eeee_rrrr_rrrr_))))
  183.       _2222   _qqqq_uuuu_eeee_uuuu_eeee______tttt _****_qqqq_;;;;
  184.       _3333   _uuuu_cccc_hhhh_aaaa_rrrr______tttt _eeee_rrrr_rrrr_;;;;
  185.       _4444  _{{{{
  186.       _5555   _mmmm_bbbb_llll_kkkk______tttt _****_bbbb_pppp_;;;;
  187.       _6666   _llll_oooo_nnnn_gggg _ffff_llll_====_0000_;;;;
  188.       _7777   _iiii_ffff _((((_((((_bbbb_pppp _==== _aaaa_llll_llll_oooo_cccc_bbbb_((((_1111_,,,, _BBBB_PPPP_RRRR_IIII______HHHH_IIII_))))_)))) _====_==== _NNNN_UUUU_LLLL_LLLL_))))
  189.       _8888        _rrrr_eeee_tttt_uuuu_rrrr_nnnn_((((_0000_))))_;;;;
  190.       _9999   _bbbb_pppp_----_>>>>_bbbb______dddd_aaaa_tttt_aaaa_pppp_----_>>>>_dddd_bbbb______tttt_yyyy_pppp_eeee _==== _MMMM______EEEE_RRRR_RRRR_OOOO_RRRR_;;;;
  191.      _1111_0000   _****_bbbb_pppp_----_>>>>_bbbb______wwww_pppp_tttt_rrrr_++++_++++ _==== _eeee_rrrr_rrrr_;;;;
  192.      _1111_1111   _((((_vvvv_oooo_iiii_dddd_)))) _ssss_tttt_rrrr_qqqq_gggg_eeee_tttt_((((_qqqq_,,,, _QQQQ_FFFF_LLLL_AAAA_GGGG_,,,, _0000_,,,, _&&&&_ffff_llll_))))_;;;;
  193.      _1111_2222   _iiii_ffff _((((_ffff_llll _&&&& _QQQQ_RRRR_EEEE_AAAA_DDDD_RRRR_))))_))))
  194.      _1111_3333        _qqqq _==== _RRRR_DDDD_((((_qqqq_))))_;;;;
  195.      _1111_4444   _pppp_uuuu_tttt_nnnn_eeee_xxxx_tttt_((((_qqqq_,,,, _bbbb_pppp_))))_;;;;
  196.      _1111_5555   _rrrr_eeee_tttt_uuuu_rrrr_nnnn_((((_1111_))))_;;;;
  197.      _1111_6666  _}}}}
  198.  
  199. RRRREEEEFFFFEEEERRRREEEENNNNCCCCEEEESSSS
  200.      _bbbb_uuuu_ffff_cccc_aaaa_llll_llll(D3), _eeee_ssss_bbbb_aaaa_llll_llll_oooo_cccc(D3), _eeee_ssss_bbbb_bbbb_cccc_aaaa_llll_llll(D3), _ffff_rrrr_eeee_eeee_bbbb(D3), _mmmm_ssss_gggg_bbbb(D4)
  201.  
  202.  
  203.  
  204.  
  205.  
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  217.  
  218.  
  219.                                                                         PPPPaaaaggggeeee 2222
  220.  
  221.  
  222.  
  223.