Annotation of prex-old/doc/html/doc/kapi.html, Revision 1.1
1.1 ! nbrk 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
! 2: <html>
! 3: <head>
! 4: <title>Prex Kernel API Reference</title>
! 5: <meta content="text/html; charset=ISO-8859-1" http-equiv="content-type">
! 6: <meta name="keywords" content="Prex, embedded, real-time, operating system, RTOS, open source, free">
! 7: <meta name="author" content="Kohsuke Ohtani">
! 8: <link rel="stylesheet" type="text/css" href="../default.css" media="screen">
! 9: <link rel="stylesheet" type="text/css" href="../print.css" media="print">
! 10: </head>
! 11: <body>
! 12: <div id="top">
! 13: </div>
! 14: <div id="middle">
! 15:
! 16: <table id="content" cellpadding="0" cellspacing="0">
! 17: <tbody>
! 18:
! 19: <tr>
! 20: <td id="header" colspan="2" valign="top">
! 21: <table width="100%" border="0" cellspacing="0" cellpadding="0">
! 22: <tr>
! 23: <td id="logo">
! 24: <a href="http://prex.sourceforge.net/">
! 25: <img alt="Prex logo" src="../img/logo.gif" border="0"
! 26: style="width: 281px; height: 56px;"></a>
! 27: </td>
! 28: <td id="brief" align="right" valign="bottom">
! 29: An Open Source, Royalty-free,<br>
! 30: Real-time Operating System
! 31: </td>
! 32: </tr>
! 33: </table>
! 34: </td>
! 35: </tr
! 36:
! 37: <tr>
! 38: <td id="directory" style="vertical-align: top;">
! 39: <a href="http://prex.sourceforge.net/">Prex Home</a> >
! 40: <a href="index.html">Document Index</a> >
! 41: Kernel API Reference
! 42: </tr>
! 43: <tr><td class="pad" colspan="2" style="vertical-align: top;"></td></tr>
! 44:
! 45: <tr>
! 46: <td id="main" style="vertical-align: top;">
! 47: <h1>Prex Kernel API Reference</h1>
! 48:
! 49: <i>Version 1.7.0, 2007/12/24</i><br>
! 50: <br>
! 51:
! 52: <h3>Table of Contents</h3>
! 53:
! 54: <ul>
! 55: <li><a href="#intro">Introduction</a></li>
! 56: </ul>
! 57:
! 58: <ul>
! 59: <li><a href="#gen">General Information</a>
! 60: <ul>
! 61: <li><a href="#type">Data Types</a></li>
! 62: <li><a href="#err">Error Numbers</a></li>
! 63: </ul>
! 64: </li>
! 65: </ul>
! 66:
! 67: <ul>
! 68: <li><a href="#obj">Object</a>
! 69: <ul>
! 70: <li><a href="#obj0">object_create</a></li>
! 71: <li><a href="#obj1">object_delete</a></li>
! 72: <li><a href="#obj2">object_lookup</a></li>
! 73: </ul>
! 74: </li>
! 75: </ul>
! 76:
! 77: <ul>
! 78: <li><a href="#msg">Message</a>
! 79: <ul>
! 80: <li><a href="#msg0">msg_send</a></li>
! 81: <li><a href="#msg1">msg_receive</a></li>
! 82: <li><a href="#msg2">msg_reply</a></li>
! 83: </ul>
! 84: </li>
! 85: </ul>
! 86:
! 87: <ul>
! 88: <li><a href="#task">Task</a>
! 89: <ul>
! 90: <li><a href="#task0">task_create</a></li>
! 91: <li><a href="#task1">task_terminate</a></li>
! 92: <li><a href="#task2">task_self</a></li>
! 93: <li><a href="#task3">task_suspend</a></li>
! 94: <li><a href="#task4">task_resume</a></li>
! 95: <li><a href="#task5">task_name</a></li>
! 96: <li><a href="#task6">task_getcap</a></li>
! 97: <li><a href="#task7">task_setcap</a></li>
! 98: </ul>
! 99: </li>
! 100: </ul>
! 101:
! 102: <ul>
! 103: <li><a href="#thr">Thread</a>
! 104: <ul>
! 105: <li><a href="#thr0">thread_create</a></li>
! 106: <li><a href="#thr1">thread_terminate</a></li>
! 107: <li><a href="#thr2">thread_load</a></li>
! 108: <li><a href="#thr3">thread_self</a></li>
! 109: <li><a href="#thr4">thread_yield</a></li>
! 110: <li><a href="#thr5">thread_suspend</a></li>
! 111: <li><a href="#thr6">thread_resume</a></li>
! 112: <li><a href="#thr7">thread_schedparam</a></li>
! 113: </ul>
! 114: </li>
! 115: </ul>
! 116:
! 117: <ul>
! 118: <li><a href="#vm">Virtual Memory</a>
! 119: <ul>
! 120: <li><a href="#vm0">vm_allocate</a></li>
! 121: <li><a href="#vm1">vm_free</a></li>
! 122: <li><a href="#vm2">vm_attribute</a></li>
! 123: <li><a href="#vm3">vm_map</a></li>
! 124: </ul>
! 125: </li>
! 126: </ul>
! 127:
! 128: <ul>
! 129: <li><a href="#tmr">Timer</a>
! 130: <ul>
! 131: <li><a href="#tmr0">timer_sleep</a></li>
! 132: <li><a href="#tmr1">timer_alarm</a></li>
! 133: <li><a href="#tmr2">timer_periodic</a></li>
! 134: <li><a href="#tmr3">timer_waitperiod</a></li>
! 135: </ul>
! 136: </li>
! 137: </ul>
! 138:
! 139: <ul>
! 140: <li><a href="#ex">Exception</a>
! 141: <ul>
! 142: <li><a href="#ex0">exception_setup</a></li>
! 143: <li><a href="#ex1">exception_return</a></li>
! 144: <li><a href="#ex2">exception_raise</a></li>
! 145: <li><a href="#ex3">exception_wait</a></li>
! 146: </ul>
! 147: </li>
! 148: </ul>
! 149:
! 150: <ul>
! 151: <li><a href="#dev">Device</a>
! 152: <ul>
! 153: <li><a href="#dev0">device_open</a></li>
! 154: <li><a href="#dev1">device_close</a></li>
! 155: <li><a href="#dev2">device_read</a></li>
! 156: <li><a href="#dev3">device_write</a></li>
! 157: <li><a href="#dev4">device_ioctl</a></li>
! 158: </ul>
! 159: </li>
! 160: </ul>
! 161:
! 162: <ul>
! 163: <li><a href="#mu">Mutex</a>
! 164: <ul>
! 165: <li><a href="#mu0">mutex_init</a></li>
! 166: <li><a href="#mu1">mutex_destroy</a></li>
! 167: <li><a href="#mu2">mutex_trylock</a></li>
! 168: <li><a href="#mu3">mutex_lock</a></li>
! 169: <li><a href="#mu4">mutex_unlock</a></li>
! 170: </ul>
! 171: </li>
! 172: </ul>
! 173:
! 174: <ul>
! 175: <li><a href="#cv">Condition Variable</a>
! 176: <ul>
! 177: <li><a href="#cv0">cond_init</a></li>
! 178: <li><a href="#cv1">cond_destroy</a></li>
! 179: <li><a href="#cv2">cond_wait</a></li>
! 180: <li><a href="#cv3">cond_signal</a></li>
! 181: <li><a href="#cv4">cond_broadcast</a></li>
! 182: </ul>
! 183: </li>
! 184: </ul>
! 185:
! 186: <ul>
! 187: <li><a href="#sem">Semaphore</a>
! 188: <ul>
! 189: <li><a href="#sem0">sem_init</a></li>
! 190: <li><a href="#sem1">sem_destroy</a></li>
! 191: <li><a href="#sem2">sem_wait</a></li>
! 192: <li><a href="#sem3">sem_trywait</a></li>
! 193: <li><a href="#sem4">sem_post</a></li>
! 194: <li><a href="#sem5">sem_getvalue</a></li>
! 195: </ul>
! 196: </li>
! 197: </ul>
! 198:
! 199: <ul>
! 200: <li><a href="#sys">System</a>
! 201: <ul>
! 202: <li><a href="#sys0">sys_log</a></li>
! 203: <li><a href="#sys1">sys_panic</a></li>
! 204: <li><a href="#sys2">sys_info</a></li>
! 205: <li><a href="#sys3">sys_time</a></li>
! 206: <li><a href="#sys4">sys_debug</a></li>
! 207: </ul>
! 208:
! 209: </ul>
! 210:
! 211:
! 212: <h2 id="intro">Introduction</h2>
! 213: <p>
! 214: The Prex Kernel API Reference define a programming interface
! 215: for the Prex applications.
! 216: This document includes the complete set of kernel services and the detailed
! 217: description.
! 218: </p>
! 219:
! 220:
! 221: <h2 id="gen">General Information</h2>
! 222:
! 223: <h3 id="type">Data Types</h3>
! 224: <p>
! 225: The following data types are supported by the Prex kernel.
! 226: Each type represents ID of the kernel element.
! 227: </p>
! 228:
! 229: <table border="1" width="60%" cellspacing="0">
! 230: <tbody>
! 231: <tr>
! 232: <th>Data type</th>
! 233: <th>Description</th>
! 234: </tr>
! 235: <tr>
! 236: <td>object_t</td>
! 237: <td>Used to identify a object.</td>
! 238: </tr>
! 239: <tr>
! 240: <td>task_t</td>
! 241: <td>Used to identify a task.</td>
! 242: </tr>
! 243: <tr>
! 244: <td>thread_t</td>
! 245: <td>Used to identify a thread.</td>
! 246: </tr>
! 247: <tr>
! 248: <td>device_t</td>
! 249: <td>Used to identify a device.</td>
! 250: </tr>
! 251: <tr>
! 252: <td>mutex_t</td>
! 253: <td>Used to identify a mutex.</td>
! 254: </tr>
! 255: <tr>
! 256: <td>cond_t</td>
! 257: <td>Used to identify a condition variable.</td>
! 258: </tr>
! 259: <tr>
! 260: <td>sem_t</td>
! 261: <td>Used to identify a semaphore.</td>
! 262: </tr>
! 263: <tr>
! 264: <td>cap_t</td>
! 265: <td>Used to represent a task capability.</td>
! 266: </tr>
! 267:
! 268: </tbody>
! 269: </table>
! 270:
! 271:
! 272: <h3 id="err">Error Numbers</h3>
! 273: <p>
! 274: The definition of the Prex kernel error is compatible with the POSIX
! 275: error number. However, unlike POSIX, Prex does not use an errno variable
! 276: because errno is not MT-safe. So, most functions in kernel API will
! 277: provide an error number as a return value.
! 278: </p>
! 279: <p>
! 280: The following error names are used as the possible error number.
! 281: </p>
! 282: <dl>
! 283: <dt>[EPERM]</dt>
! 284: <dd>Operation not permitted.</dd>
! 285: <dt>[ENOENT]</dt>
! 286: <dd>No such file or directory.</dd>
! 287: <dt>[ESRCH]</dt>
! 288: <dd>No such process.</dd>
! 289: <dt>[EINTR]</dt>
! 290: <dd>Interrupted system call.</dd>
! 291: <dt>[EIO]</dt>
! 292: <dd>I/O error.</dd>
! 293: <dt>[ENXIO]</dt>
! 294: <dd>No such device or address.</dd>
! 295: <dt>[EAGAIN]</dt>
! 296: <dd>Try again.</dd>
! 297: <dt>[ENOMEM]</dt>
! 298: <dd>Out of memory.</dd>
! 299: <dt>[EACCES]</dt>
! 300: <dd>Permission denied.</dd>
! 301: <dt>[EFAULT]</dt>
! 302: <dd>Bad address.</dd>
! 303: <dt>[EBUSY]</dt>
! 304: <dd>Device or resource busy.</dd>
! 305: <dt>[EEXIST]</dt>
! 306: <dd>File exists.</dd>
! 307: <dt>[ENODEV]</dt>
! 308: <dd>No such device.</dd>
! 309: <dt>[EINVAL]</dt>
! 310: <dd>Invalid argument.</dd>
! 311: <dt>[ERANGE]</dt>
! 312: <dd>Math result not representable.</dd>
! 313: <dt>[EDEADLK]</dt>
! 314: <dd>Resource deadlock avoided.</dd>
! 315: <dt>[ENOSYS]</dt>
! 316: <dd>Function not implemented.</dd>
! 317: <dt>[ENAMETOOLONG]</dt>
! 318: <dd>File name too long.</dd>
! 319: <dt>[ETIMEDOUT]</dt>
! 320: <dd>Timed out.</dd>
! 321:
! 322: </dl>
! 323:
! 324: <h2 id="obj">Object</h2>
! 325:
! 326: <h3 id="obj0">NAME</h3>
! 327: object_create() - create a new object
! 328:
! 329: <h3>SYNOPSIS</h3>
! 330: <pre>
! 331: int object_create(const char *name, object_t *obj);
! 332: </pre>
! 333:
! 334: <h3>DESCRIPTION</h3>
! 335: The object_create() function creates a new object.
! 336: The ID of the new object is stored in <i>obj</i> on success.
! 337: <br><br>
! 338: The name of the object must be unique in the system.
! 339: Or, the object can be created without name by setting NULL
! 340: as <i>name</i> argument. This object can be used as a private object
! 341: which can be accessed only by threads in the same task.
! 342:
! 343: <h3>ERRORS</h3>
! 344: <dl>
! 345: <dt>[EFAULT]</dt>
! 346: <dd>The address of <i>name</i> or <i>obj</i> is inaccessible.</dd>
! 347: <dt>[ENAMETOOLONG]</dt>
! 348: <dd>The length of the <i>name</i> argument exceeds MAX_OBJNAME.</dd>
! 349: <dt>[EEXIST]</dt>
! 350: <dd>The named object already exists.</dd>
! 351: <dt>[ENOMEM]</dt>
! 352: <dd>The system is unable to allocate resources.</dd>
! 353: </dl>
! 354: <br>
! 355: <hr size="1">
! 356:
! 357:
! 358: <h3 id="obj1">NAME</h3>
! 359: object_delete() - delete an object
! 360:
! 361: <h3>SYNOPSIS</h3>
! 362: <pre>
! 363: int object_delete(object_t obj);
! 364: </pre>
! 365:
! 366: <h3>DESCRIPTION</h3>
! 367: The object_delete() function deletes the object specified by <i>obj</i>.
! 368: <br><br>
! 369: A thread can delete the object only when the target object is created
! 370: by the thread of the same task.
! 371: All pending messages related to the deleted object are automatically canceled.
! 372:
! 373: <h3>ERRORS</h3>
! 374: <dl>
! 375: <dt>[EINVAL]</dt>
! 376: <dd>The specified <i>obj</i> is not a valid object ID.</dd>
! 377: <dt>[EACCESS]</dt>
! 378: <dd>The thread is not allowed to delete the object.</dd>
! 379: </dl>
! 380: <br>
! 381: <hr size="1">
! 382:
! 383:
! 384: <h3 id="obj2">NAME</h3>
! 385: object_lookup() - lookup an object
! 386:
! 387: <h3>SYNOPSIS</h3>
! 388: <pre>
! 389: int object_lookup(const char *name, object_t *obj);
! 390: </pre>
! 391:
! 392: <h3>DESCRIPTION</h3>
! 393: The object_lookup() function searches an object in the object name space.
! 394: The <i>name</i> argument is the null-terminated string.
! 395: The object ID is returned in <i>obj</i> on success.
! 396:
! 397: <h3>ERRORS</h3>
! 398: <dl>
! 399: <dt>[EFAULT]</dt>
! 400: <dd>The address of <i>name</i> or <i>obj</i> is inaccessible.</dd>
! 401: <dt>[ESRCH]</dt>
! 402: <dd>The length of the <i>name</i> argument exceeds MAX_OBJNAME.</dd>
! 403: <dt>[ENOENT]</dt>
! 404: <dd>The specified object does not exist.</dd>
! 405: </dl>
! 406: <br>
! 407:
! 408:
! 409: <h2 id="msg">Message</h2>
! 410:
! 411: <h3 id="msg0">NAME</h3>
! 412: msg_send() - send a message
! 413:
! 414: <h3>SYNOPSIS</h3>
! 415: <pre>
! 416: int msg_send(object_t obj, void *msg, size_t size);
! 417: </pre>
! 418:
! 419: <h3>DESCRIPTION</h3>
! 420: The msg_send() function sends a message to an object.
! 421: The caller thread will be blocked until any other thread receives
! 422: the message and calls msg_reply() for this object.
! 423: A thread can send a message to any object if it knows the object ID.
! 424: <br><br>
! 425: The <i>size</i> argument specifies the size of the message buffer to send.
! 426: <br><br>
! 427: The message is the binary data block which includes a message header.
! 428: The kernel does not touch the message body, and it is
! 429: necessary to recognize the predefined message format between sender
! 430: and receiver.
! 431:
! 432: <h3>ERRORS</h3>
! 433: <dl>
! 434: <dt>[EINVAL]</dt>
! 435: <dd>The specified <i>obj</i> is not a valid object ID.</dd>
! 436: <dt>[EFAULT]</dt>
! 437: <dd>The buffer of <i>msg</i> is inaccessible.</dd>
! 438: <dt>[EDEADLK]</dt>
! 439: <dd><i>obj</i> is the object that the caller thread is receiving from now.</dd>
! 440: <dt>[EAGAIN]</dt>
! 441: <dd>The receiver thread has been terminated.</dd>
! 442: <dt>[EINTR]</dt>
! 443: <dd>The function was interrupted by an exception.</dd>
! 444: <dt>[EPERM]</dt>
! 445: <dd>The caller task is not an owner of the <i>obj</i>, but it
! 446: does not have CAP_IPC capability.</dd>
! 447: </dl>
! 448: <br>
! 449: <hr size="1">
! 450:
! 451:
! 452: <h3 id="msg1">NAME</h3>
! 453: msg_receive() - receive a message
! 454:
! 455: <h3>SYNOPSIS</h3>
! 456: <pre>
! 457: int msg_receive(object_t obj, void *msg, size_t size);
! 458: </pre>
! 459:
! 460: <h3>DESCRIPTION</h3>
! 461: The msg_receive() function receives a message from an object.
! 462: A thread can receive a message from the object which was created
! 463: by the thread in the same task. If the message has not arrived, the
! 464: caller thread blocks until any message comes in.
! 465: <br><br>
! 466: The <i>size</i> argument specifies the "maximum" size of the message
! 467: buffer to receive. If the sent message is larger than this size,
! 468: the kernel will automatically clip the message to the receive buffer size.
! 469: <br><br>
! 470: A thread can not receive the multiple messages at once.
! 471:
! 472: <h3>ERRORS</h3>
! 473: <dl>
! 474: <dt>[EINVAL]</dt>
! 475: <dd>The specified <i>obj</i> is not a valid object ID.</dd>
! 476: <dt>[EACCESS]</dt>
! 477: <dd>The caller task is not the owner of the target object.</dd>
! 478: <dt>[EBUSY]</dt>
! 479: <dd>The caller thread does not finish the previous receive operation.</dd>
! 480: <dt>[EFAULT]</dt>
! 481: <dd>The buffer of <i>msg</i> is inaccessible.</dd>
! 482: <dt>[EINTR]</dt>
! 483: <dd>The function was interrupted by an exception.</dd>
! 484: </dl>
! 485: <br>
! 486: <hr size="1">
! 487:
! 488:
! 489: <h3 id="msg2">NAME</h3>
! 490: msg_reply() - reply to an object
! 491:
! 492: <h3>SYNOPSIS</h3>
! 493: <pre>
! 494: int msg_reply(object_t obj, void *msg, size_t size);
! 495: </pre>
! 496:
! 497: <h3>DESCRIPTION</h3>
! 498: The msg_reply() function sends a reply message to the object.
! 499: A thread must reply to the correct object that the thread
! 500: preciously received from. Otherwise, this function will be failed.
! 501: <br><br>
! 502: The <i>size</i> argument specifies the size of the message buffer to reply.
! 503:
! 504: <h3>ERRORS</h3>
! 505: <dl>
! 506: <dt>[EINVAL]</dt>
! 507: <dd>The specified <i>obj</i> is not a valid object ID. Or, the sender
! 508: thread has been terminated.</dd>
! 509: <dt>[EFAULT]</dt>
! 510: <dd>The buffer of <i>msg</i> is inaccessible.</dd>
! 511: </dl>
! 512: <br>
! 513:
! 514:
! 515: <h2 id="task">Task</h2>
! 516:
! 517: <h3 id="task0">NAME</h3>
! 518: task_create() - create a new task
! 519:
! 520: <h3>SYNOPSIS</h3>
! 521: <pre>
! 522: int task_create(task_t parent, int vm_option, task_t *child);
! 523: </pre>
! 524:
! 525: <h3>DESCRIPTION</h3>
! 526: The task_create() function create a new task.
! 527: If <i>vm_option</i> option can be one of the following:
! 528: <ul>
! 529: <li>VM_NEW - The new task has clean memory image.</li>
! 530: <li>VM_COPY - The new task will have the duplicated memory image with the parent task.</li>
! 531: <li>VM_SHARE - The new task will share the same memory image with the parent task.</li>
! 532: </ul>
! 533: The child task initially contains no threads.
! 534: So, the caller task must create new thread under the child task to
! 535: run it.
! 536: <br><br>
! 537: <i>vm_option</i> flag is supported only with MMU system. The created
! 538: task has always new memory map with NOMMU system.
! 539: <br><br>
! 540: The function returns the created task ID in <i>child</i>,
! 541: and child task will receive 0 as <i>child</i>.
! 542:
! 543: <h3>ERRORS</h3>
! 544: <dl>
! 545: <dt>[ESRCH]</dt>
! 546: <dd>The specified <i>parent</i> is not a valid task ID.</dd>
! 547: <dt>[EFAULT]</dt>
! 548: <dd>The address of <i>child</i> is inaccessible.</dd>
! 549: <dt>[ENOMEM]</dt>
! 550: <dd>The system is unable to allocate resources.</dd>
! 551: <dt>[EPERM]</dt>
! 552: <dd>The specified <i>parent</i> is not a current task, but the caller
! 553: task does not have CAP_TASK capability.</dd>
! 554: </dl>
! 555: <br>
! 556: <hr size="1">
! 557:
! 558:
! 559: <h3 id="task1">NAME</h3>
! 560: task_terminate() - terminate a task
! 561:
! 562: <h3>SYNOPSIS</h3>
! 563: <pre>
! 564: int task_terminate(task_t task);
! 565: </pre>
! 566:
! 567: <h3>DESCRIPTION</h3>
! 568: The task_terminate() function terminates a task and deallocates all resource
! 569: for the task.
! 570: <br><br>
! 571: If the <i>task</i> argument point to the current task, this routine never returns.
! 572:
! 573: <h3>ERRORS</h3>
! 574: <dl>
! 575: <dt>[ESRCH]</dt>
! 576: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 577: <dt>[EPERM]</dt>
! 578: <dd>The specified <i>task</i> is not a current task, but the caller
! 579: task does not have CAP_TASK capability.</dd>
! 580: </dl>
! 581: <br>
! 582: <hr size="1">
! 583:
! 584:
! 585: <h3 id="task2">NAME</h3>
! 586: task_self() - return task ID
! 587:
! 588: <h3>SYNOPSIS</h3>
! 589: <pre>
! 590: task_t task_self(void);
! 591: </pre>
! 592:
! 593: <h3>DESCRIPTION</h3>
! 594: The task_self() function returns ID of the current task.
! 595:
! 596: <h3>RETURN VALUE</h3>
! 597: Current task ID.
! 598: <br>
! 599: <br>
! 600: <hr size="1">
! 601:
! 602:
! 603: <h3 id="task3">NAME</h3>
! 604: task_suspend() - suspend a task
! 605:
! 606: <h3>SYNOPSIS</h3>
! 607: <pre>
! 608: int task_suspend(task_t task);
! 609: </pre>
! 610:
! 611: <h3>DESCRIPTION</h3>
! 612: The task_suspend() function suspends all threads within the specified task.
! 613:
! 614: <h3>ERRORS</h3>
! 615: <dl>
! 616: <dt>[EINVAL]</dt>
! 617: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 618: <dt>[ESRCH]</dt>
! 619: <dd>The specified <i>task</i> is not a current task, but the caller
! 620: task does not have CAP_TASK capability.</dd>
! 621: </dl>
! 622: <br>
! 623: <hr size="1">
! 624:
! 625:
! 626: <h3 id="task4">NAME</h3>
! 627: task_resume() - resume a task
! 628:
! 629: <h3>SYNOPSIS</h3>
! 630: <pre>
! 631: int task_resume(task_t task);
! 632: </pre>
! 633:
! 634: <h3>DESCRIPTION</h3>
! 635: The task_resume() function resumes all threads within the specified task.
! 636:
! 637: <h3>ERRORS</h3>
! 638: <dl>
! 639: <dt>[ESRCH]</dt>
! 640: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 641: <dt>[EINVAL]</dt>
! 642: <dd>The specified <i>task</i> is not suspended now.</dd>
! 643: <dt>[EPERM]</dt>
! 644: <dd>The specified <i>task</i> is not a current task, but the caller
! 645: task does not have CAP_TASK capability.</dd>
! 646: </dl>
! 647: <br>
! 648: <hr size="1">
! 649:
! 650:
! 651: <h3 id="task5">NAME</h3>
! 652: task_name() - set task name
! 653:
! 654: <h3>SYNOPSIS</h3>
! 655: <pre>
! 656: int task_name(task_t task, const char *name);
! 657: </pre>
! 658:
! 659: <h3>DESCRIPTION</h3>
! 660: The task_name() function set the name of the specified task. The task name can
! 661: be changed at any time.
! 662: <br><br>
! 663: This function does not returns error even if the same task name already
! 664: exists in the system.
! 665:
! 666: <h3>ERRORS</h3>
! 667: <dl>
! 668: <dt>[ESRCH]</dt>
! 669: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 670: <dt>[EFAULT]</dt>
! 671: <dd>The address of <i>name</i> is inaccessible.</dd>
! 672: <dt>[ENAMETOOLONG]</dt>
! 673: <dd>The length of the <i>name</i> argument exceeds MAX_TASKNAME.</dd>
! 674: <dt>[EPERM]</dt>
! 675: <dd>The specified <i>task</i> is not a current task, but the caller
! 676: task does not have CAP_TASK capability.</dd>
! 677: </dl>
! 678: <br>
! 679: <hr size="1">
! 680:
! 681: <h3 id="task6">NAME</h3>
! 682: task_getcap() - get a task capability
! 683:
! 684: <h3>SYNOPSIS</h3>
! 685: <pre>
! 686: int task_getcap(task_t task, cap_t *cap);
! 687: </pre>
! 688:
! 689: <h3>DESCRIPTION</h3>
! 690: <p>
! 691: The task_getcap() function returns the capability of the
! 692: specified task.
! 693: </p>
! 694:
! 695:
! 696: <h3>ERRORS</h3>
! 697: <dl>
! 698: <dt>[ESRCH]</dt>
! 699: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 700: <dt>[EFAULT]</dt>
! 701: <dd>The address of <i>cap</i> is inaccessible.</dd>
! 702: </dl>
! 703: <br>
! 704:
! 705:
! 706: <hr size="1">
! 707:
! 708: <h3 id="task7">NAME</h3>
! 709: task_setcap() - set a task capability
! 710:
! 711: <h3>SYNOPSIS</h3>
! 712: <pre>
! 713: int task_setcap(task_t task, cap_t *cap);
! 714: </pre>
! 715:
! 716: <h3>DESCRIPTION</h3>
! 717: <p>
! 718: The task_setcap() function set the capability of the
! 719: specified task.
! 720: </p>
! 721: <p>
! 722: The following task capabilities are supported.
! 723: </p>
! 724: <dl>
! 725: <dt>CAP_SETPCAP</dt>
! 726: <dd>Allow setting capability.</dd>
! 727: <dt>CAP_TASK</dt>
! 728: <dd>Allow controlling another task's execution.</dd>
! 729: <dt>CAP_MEMORY</dt>
! 730: <dd>Allow touching another task's memory.</dd>
! 731: <dt>CAP_KILL</dt>
! 732: <dd>Allow raising exception to another task.</dd>
! 733: <dt>CAP_SEMAPHORE</dt>
! 734: <dd>Allow accessing another task's semaphore.</dd>
! 735: <dt>CAP_NICE</dt>
! 736: <dd>Allow changing scheduling parameter.</dd>
! 737: <dt>CAP_IPC</dt>
! 738: <dd>Allow accessing another task's IPC object.</dd>
! 739: <dt>CAP_DEVIO</dt>
! 740: <dd>Allow device I/O operations.</dd>
! 741: <dt>CAP_POWER</dt>
! 742: <dd>Allow power control including shutdown.</dd>
! 743: <dt>CAP_TIME</dt>
! 744: <dd>Allow setting system time.</dd>
! 745: <dt>CAP_RAWIO</dt>
! 746: <dd>Allow direct I/O access.</dd>
! 747: <dt>CAP_MOUNT</dt>
! 748: <dd>Allow mounting a file system.</dd>
! 749: <dt>CAP_CHROOT</dt>
! 750: <dd>Allow changing a root directory.</dd>
! 751: </dl>
! 752:
! 753: <h3>ERRORS</h3>
! 754: <dl>
! 755: <dt>[ESRCH]</dt>
! 756: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 757: <dt>[EFAULT]</dt>
! 758: <dd>The address of <i>cap</i> is inaccessible.</dd>
! 759: <dt>[EPERM]</dt>
! 760: <dd>The caller task does not have CAP_SETPCAP capability.</dd>
! 761: </dl>
! 762: <br>
! 763:
! 764:
! 765: <h2 id="thr">Thread</h2>
! 766:
! 767: <h3 id="thr0">NAME</h3>
! 768: thread_create() - create a new thread
! 769:
! 770: <h3>SYNOPSIS</h3>
! 771: <pre>
! 772: int thread_create(task_t task, thread_t *th);
! 773: </pre>
! 774:
! 775: <h3>DESCRIPTION</h3>
! 776: The thread_create() function creates a new thread within <i>task</i>.
! 777: The new thread will start at the return address of the thread_create() call.
! 778: <br><br>
! 779: Since the created thread is initially set to the suspended state,
! 780: thread_resume() must be called to start it.
! 781:
! 782: <h3>ERRORS</h3>
! 783: <dl>
! 784: <dt>[ESRCH]</dt>
! 785: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 786: <dt>[EFAULT]</dt>
! 787: <dd>The address of <i>th</i> is inaccessible.</dd>
! 788: <dt>[ENOMEM]</dt>
! 789: <dd>The system is unable to allocate resources.</dd>
! 790: <dt>[EPERM]</dt>
! 791: <dd>The specified <i>task</i> is not a current task, but the caller
! 792: task does not have CAP_TASK capability.</dd>
! 793: </dl>
! 794: <br>
! 795: <hr size="1">
! 796:
! 797:
! 798: <h3 id="thr1">NAME</h3>
! 799: thread_terminate() - terminate a thread
! 800:
! 801: <h3>SYNOPSIS</h3>
! 802: <pre>
! 803: int thread_terminate(thread_t th);
! 804: </pre>
! 805:
! 806: <h3>DESCRIPTION</h3>
! 807: The thread_terminate() function terminates a thread.
! 808: It will release all resources used by the target thread.
! 809: <br><br>
! 810: If specified <i>th</i> is the current thread, this routine never returns.
! 811:
! 812: <h3>ERRORS</h3>
! 813: <dl>
! 814: <dt>[ESRCH]</dt>
! 815: <dd>The specified thread <i>th</i> is not a valid thread ID.</dd>
! 816: <dt>[EPERM]</dt>
! 817: <dd>The caller task is not an owner of the specified <i>th</i>, but the caller
! 818: task does not have CAP_TASK capability.</dd>
! 819: </dl>
! 820: <br>
! 821: <hr size="1">
! 822:
! 823:
! 824: <h3 id="thr2">NAME</h3>
! 825: thread_load() - load the thread state
! 826:
! 827: <h3>SYNOPSIS</h3>
! 828: <pre>
! 829: int thread_load(thread_t th, void *entry, void *stack);
! 830: </pre>
! 831:
! 832: <h3>DESCRIPTION</h3>
! 833: The thread_load() function loads the thread state (program counter and
! 834: stack pointer).
! 835: <br><br>
! 836: The <i>entry</i> or <i>stack</i> argument can be set to NULL. In this
! 837: case, the previous state is used.
! 838:
! 839: <h3>ERRORS</h3>
! 840: <dl>
! 841: <dt>[ESRCH]</dt>
! 842: <dd>The specified <i>th</i> is not a valid thread ID.</dd>
! 843: <dt>[EINVAL]</dt>
! 844: <dd><i>entry</i> or <i>stack</i> is not a valid address.</dd>
! 845: <dt>[EPERM]</dt>
! 846: <dd>The caller task is not an owner of the specified <i>th</i>, but the caller
! 847: task does not have CAP_TASK capability.</dd>
! 848: </dl>
! 849: <br>
! 850: <hr size="1">
! 851:
! 852:
! 853: <h3 id="thr3">NAME</h3>
! 854: thread_self() - return thread ID
! 855:
! 856: <h3>SYNOPSIS</h3>
! 857: <pre>
! 858: thread_t thread_self(void);
! 859: </pre>
! 860:
! 861: <h3>DESCRIPTION</h3>
! 862: The thread_self() function returns ID of the current thread.
! 863:
! 864: <h3>RETURN VALUE</h3>
! 865: Current thread ID.
! 866: <br>
! 867: <br>
! 868: <hr size="1">
! 869:
! 870:
! 871: <h3 id="thr4">NAME</h3>
! 872: thread_yield() - yield the processor
! 873:
! 874: <h3>SYNOPSIS</h3>
! 875: <pre>
! 876: void thread_yield(void);
! 877: </pre>
! 878:
! 879: <h3>DESCRIPTION</h3>
! 880: The thread_yield() function forces the current thread to release
! 881: the processor.
! 882:
! 883: <h3>ERRORS</h3>
! 884: No errors are defined.
! 885: <br>
! 886: <br>
! 887: <hr size="1">
! 888:
! 889:
! 890: <h3 id="thr5">NAME</h3>
! 891: thread_suspend() - suspend a thread
! 892:
! 893: <h3>SYNOPSIS</h3>
! 894: <pre>
! 895: int thread_suspend(thread_t th);
! 896: </pre>
! 897:
! 898: <h3>DESCRIPTION</h3>
! 899: The thread_suspend() function suspends the specified thread.
! 900: Although a thread can be suspended any number of times,
! 901: it does not start to run unless it is resumed by the same
! 902: number of suspend.
! 903:
! 904: <h3>ERRORS</h3>
! 905: <dl>
! 906: <dt>[ESRCH]</dt>
! 907: <dd>The specified <i>th</i> is not a valid thread ID.</dd>
! 908: <dt>[EPERM]</dt>
! 909: <dd>The caller task is not an owner of the specified <i>th</i>, but the caller
! 910: task does not have CAP_TASK capability.</dd>
! 911: </dl>
! 912: <br>
! 913: <hr size="1">
! 914:
! 915:
! 916: <h3 id="thr6">NAME</h3>
! 917: thread_resume() - resume a thread
! 918:
! 919: <h3>SYNOPSIS</h3>
! 920: <pre>
! 921: int thread_resume(thread_t th);
! 922: </pre>
! 923:
! 924: <h3>DESCRIPTION</h3>
! 925: The thread_resume() function resumes the specified thread.
! 926: A thread does not begin to run, unless both a thread suspend
! 927: count and a task suspend count are set to 0.
! 928:
! 929: <h3>ERRORS</h3>
! 930: <dl>
! 931: <dt>[ESRCH]</dt>
! 932: <dd>The specified <i>th</i> is not a valid thread ID.</dd>
! 933: <dt>[EINVAL]</dt>
! 934: <dd>The specified <i>th</i> is not suspended now.</dd>
! 935: <dt>[EPERM]</dt>
! 936: <dd>The caller task is not an owner of the specified <i>th</i>, but the caller
! 937: task does not have CAP_TASK capability.</dd>
! 938: </dl>
! 939: <br>
! 940: <hr size="1">
! 941:
! 942:
! 943: <h3 id="thr7">NAME</h3>
! 944: thread_schedparam() - get/set scheduling parameters
! 945:
! 946: <h3>SYNOPSIS</h3>
! 947: <pre>
! 948: int thread_schedparam(thread_t th, int op, int *param);
! 949: </pre>
! 950:
! 951: <h3>DESCRIPTION</h3>
! 952: The thread_schedparam() function gets/sets the various scheduling parameter.
! 953: <i>op</i> argument is an operation ID which is one of the following value.
! 954: <ul>
! 955: <li>OP_GETPRIO - get the scheduling priority</li>
! 956: <li>OP_SETPRIO - set the scheduling priority</li>
! 957: <li>OP_GETPOLICY - get the scheduling policy</li>
! 958: <li>OP_SETPOLICY - set the scheduling policy</li>
! 959: </ul>
! 960: The kernel supports the following scheduling policy.
! 961: <ul>
! 962: <li>SCHED_FIFO - First-in First-out</li>
! 963: <li>SCHED_RR - Round Robin</li>
! 964: </ul>
! 965:
! 966: <h3>ERRORS</h3>
! 967: <dl>
! 968: <dt>[ESRCH]</dt>
! 969: <dd>The specified <i>th</i> is not a valid thread ID.</dd>
! 970: <dt>[EFAULT]</dt>
! 971: <dd>The address of <i>param</i> is inaccessible.</dd>
! 972: <dt>[EINVAL]</dt>
! 973: <dd>The kernel does not support the specified policy.</dd>
! 974: <dt>[EPERM]</dt>
! 975: <dd>The caller task is not an owner of the specified <i>th</i>, or the caller
! 976: task does not have CAP_NICE capability to change the parameter.</dd>
! 977: </dl>
! 978: <br>
! 979:
! 980:
! 981:
! 982: <h2 id="vm">Virtual Memory</h2>
! 983:
! 984: <h3 id="vm0">NAME</h3>
! 985: vm_allocate() - allocate memory
! 986:
! 987: <h3>SYNOPSIS</h3>
! 988: <pre>
! 989: int vm_allocate(task_t task, void **addr, size_t size, int anywhere);
! 990: </pre>
! 991:
! 992: <h3>DESCRIPTION</h3>
! 993: The vm_allocate() function allocates a zero-filled memory in the <i>task</i>'s
! 994: memory space.
! 995: If the <i>anywhere</i> option is false, the kernel try to allocate the
! 996: memory to the address specified by <i>addr</i>. If <i>addr</i> is not
! 997: aligned to the page boundary, it will be automatically round down to one.
! 998: <i>size</i> argument is an allocation size in byte. It will also be adjusted
! 999: to the page boundary.
! 1000:
! 1001: <h3>ERRORS</h3>
! 1002: <dl>
! 1003: <dt>[ESRCH]</dt>
! 1004: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 1005: <dt>[EACCESS]</dt>
! 1006: <dd>The task is not allowed to allocate the memory to the specified address.</dd>
! 1007: <dt>[EFAULT]</dt>
! 1008: <dd>The address of <i>addr</i> is inaccessible.</dd>
! 1009: <dt>[ENOMEM]</dt>
! 1010: <dd>Not enough space.</dd>
! 1011: <dt>[EINVAL]</dt>
! 1012: <dd>The specified location is already allocated.</dd>
! 1013: <dt>[EPERM]</dt>
! 1014: <dd>The specified <i>task</i> is not a current task, but the caller
! 1015: task does not have CAP_MEMORY capability.</dd>
! 1016: </dl>
! 1017: <hr size="1">
! 1018:
! 1019:
! 1020: <h3 id="vm1">NAME</h3>
! 1021: vm_free() - free memory
! 1022:
! 1023: <h3>SYNOPSIS</h3>
! 1024: <pre>
! 1025: int vm_free(task_t task, void *addr);
! 1026: </pre>
! 1027:
! 1028: <h3>DESCRIPTION</h3>
! 1029: The vm_free() function deallocates the memory region.
! 1030: The <i>addr</i> argument must point to the memory region previously
! 1031: allocated by vm_allocate() or vm_map().
! 1032:
! 1033: <h3>ERRORS</h3>
! 1034: <dl>
! 1035: <dt>[ESRCH]</dt>
! 1036: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 1037: <dt>[EFAULT]</dt>
! 1038: <dd>The address of <i>addr</i> is inaccessible.</dd>
! 1039: <dt>[EINVAL]</dt>
! 1040: <dd>The specified location is not allocated.</dd>
! 1041: <dt>[EPERM]</dt>
! 1042: <dd>The specified <i>task</i> is not a current task, but the caller
! 1043: task does not have CAP_MEMORY capability.</dd>
! 1044: </dl>
! 1045: <hr size="1">
! 1046:
! 1047:
! 1048: <h3 id="vm2">NAME</h3>
! 1049: vm_attribute() - change memory attribute
! 1050:
! 1051: <h3>SYNOPSIS</h3>
! 1052: <pre>
! 1053: int vm_attribute(task_t task, void *addr, int attr);
! 1054: </pre>
! 1055:
! 1056: <h3>DESCRIPTION</h3>
! 1057: The vm_attribute() function changes the memory attribute.
! 1058: The <i>addr</i> argument must point to the memory region previously
! 1059: allocated by vm_allocate() or vm_map().
! 1060: The attribute type can be chosen a combination of
! 1061: ATTR_READ, ATTR_WRITE.
! 1062: Note: ATTR_EXEC is not supported, yet.
! 1063:
! 1064: <h3>ERRORS</h3>
! 1065: <dl>
! 1066: <dt>[ESRCH]</dt>
! 1067: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 1068: <dt>[EFAULT]</dt>
! 1069: <dd>The address of <i>addr</i> is inaccessible.</dd>
! 1070: <dt>[EINVAL]</dt>
! 1071: <dd>The specified location is not allocated. Or, the kernel does not
! 1072: support the specified attribute.</dd>
! 1073: <dt>[EPERM]</dt>
! 1074: <dd>The specified <i>task</i> is not a current task, but the caller
! 1075: task does not have CAP_MEMORY capability.</dd>
! 1076: </dl>
! 1077: <hr size="1">
! 1078:
! 1079:
! 1080: <h3 id="vm3">NAME</h3>
! 1081: vm_map() - map memory
! 1082:
! 1083: <h3>SYNOPSIS</h3>
! 1084: <pre>
! 1085: int vm_map(task_t task, void *addr, size_t size, void **alloc);
! 1086: </pre>
! 1087:
! 1088: <h3>DESCRIPTION</h3>
! 1089: The vm_map() function maps another task's memory to the current
! 1090: task.
! 1091: The <i>task</i> argument is the memory owner to map. The memory is
! 1092: automatically mapped to the free area of current task. The mapped
! 1093: address is stored in <i>alloc</i> on success.
! 1094:
! 1095: <h3>ERRORS</h3>
! 1096: <dl>
! 1097: <dt>[ESRCH]</dt>
! 1098: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 1099: <dt>[EFAULT]</dt>
! 1100: <dd>The address of <i>addr</i> or <i>alloc</i> is inaccessible.</dd>
! 1101: <dt>[EINVAL]</dt>
! 1102: <dd>The specified location is not allocated.</dd>
! 1103: <dt>[ENOMEM]</dt>
! 1104: <dd>Not enough space.</dd>
! 1105: <dt>[EPERM]</dt>
! 1106: <dd>The specified <i>task</i> is not a current task, but the caller
! 1107: task does not have CAP_MEMORY capability.</dd>
! 1108: </dl>
! 1109: <br>
! 1110:
! 1111: <h2 id="tmr">Timer</h2>
! 1112:
! 1113:
! 1114: <h3 id="tmr0">NAME</h3>
! 1115: timer_sleep() - sleep for a while
! 1116:
! 1117: <h3>SYNOPSIS</h3>
! 1118: <pre>
! 1119: int timer_sleep(u_long delay, u_long *remain);
! 1120: </pre>
! 1121:
! 1122: <h3>DESCRIPTION</h3>
! 1123: The timer_sleep() function stops execution of the current thread
! 1124: until specified time passed.
! 1125: The <i>delay</i> argument is the delay time in milli second.
! 1126: If this function is canceled by some reason, the remaining time
! 1127: is stored in <i>remain</i>.
! 1128:
! 1129: <h3>ERRORS</h3>
! 1130: <dl>
! 1131: <dt>[EFAULT]</dt>
! 1132: <dd>The address of <i>remain</i> is inaccessible.</dd>
! 1133: <dt>[EINTR]</dt>
! 1134: <dd>The function was interrupted by an exception.</dd>
! 1135: </dl>
! 1136: <br>
! 1137: <hr size="1">
! 1138:
! 1139:
! 1140: <h3 id="tmr1">NAME</h3>
! 1141: timer_alarm() - schedule an alarm exception
! 1142:
! 1143: <h3>SYNOPSIS</h3>
! 1144: <pre>
! 1145: int timer_alarm(u_long delay, u_long *remain);
! 1146: </pre>
! 1147:
! 1148: <h3>DESCRIPTION</h3>
! 1149: The timer_alarm() function sends EXC_ALRM exception to the caller task
! 1150: after the specified <i>delay</i> milli seconds is passed.
! 1151: If <i>delay</i> is 0, it stops the alarm timer. When the previous alarm
! 1152: timer is already working, the remaining time is stored in <i>remain</i>.
! 1153:
! 1154: <h3>ERRORS</h3>
! 1155: <dl>
! 1156: <dt>[EFAULT]</dt>
! 1157: <dd>The address of <i>remain</i> is inaccessible.</dd>
! 1158: </dl>
! 1159: <br>
! 1160: <hr size="1">
! 1161:
! 1162:
! 1163: <h3 id="tmr2">NAME</h3>
! 1164: timer_periodic() - set a periodic timer
! 1165:
! 1166: <h3>SYNOPSIS</h3>
! 1167: <pre>
! 1168: int timer_periodic(thread_t th, u_long start, u_long period);
! 1169: </pre>
! 1170:
! 1171: <h3>DESCRIPTION</h3>
! 1172: The specified thread will be woken up in specified time interval.
! 1173: The <i>start</i> argument is the first wakeup time. If <i>start</i> is 0,
! 1174: current periodic timer is stopped. <i>period</i> is the time interval
! 1175: to wakeup. The unit of <i>start</i>/<i>period</i> is milli seconds.
! 1176:
! 1177: <h3>ERRORS</h3>
! 1178: <dl>
! 1179: <dt>[ESRCH]</dt>
! 1180: <dd>The specified thread <i>th</i> is not a valid thread ID.</dd>
! 1181: <dt>[EINVAL]</dt>
! 1182: <dd><i>start</i> is 0 even when the timer is not started.</dd>
! 1183: <dt>[ENOMEM]</dt>
! 1184: <dd>The system is unable to allocate resources.</dd>
! 1185: <dt>[EPERM]</dt>
! 1186: <dd>The specified thread <i>th</i> is not in the current task.</dd>
! 1187: </dl>
! 1188: <br>
! 1189: <hr size="1">
! 1190:
! 1191:
! 1192: <h3 id="tmr3">NAME</h3>
! 1193: timer_waitperiod() - wait timer period
! 1194:
! 1195: <h3>SYNOPSIS</h3>
! 1196: <pre>
! 1197: int timer_waitperiod(void);
! 1198: </pre>
! 1199:
! 1200: <h3>DESCRIPTION</h3>
! 1201: The timer_waitperiod() function waits the next period of the current
! 1202: running periodic timer.
! 1203: <br><br>
! 1204: Since this routine returns by any exception, the control
! 1205: may return at non-period time. So, the caller must retry
! 1206: immediately if the error status is EINTR.
! 1207:
! 1208: <h3>ERRORS</h3>
! 1209: <dl>
! 1210: <dt>[EINVAL]</dt>
! 1211: <dd>The periodic timer is not started for current thread.</dd>
! 1212: <dt>[EINTR]</dt>
! 1213: <dd>The function was interrupted by an exception.</dd>
! 1214: </dl>
! 1215: <br>
! 1216:
! 1217:
! 1218:
! 1219: <h2 id="ex">Exception</h2>
! 1220:
! 1221: <h3 id="ex0">NAME</h3>
! 1222: exception_setup() - setup exception handler
! 1223:
! 1224: <h3>SYNOPSIS</h3>
! 1225: <pre>
! 1226: int exception_setup(void (*handler)(int, void *));
! 1227: </pre>
! 1228:
! 1229: <h3>DESCRIPTION</h3>
! 1230: Setup an exception handler for the current task.
! 1231: NULL can be specified as <i>handler</i> to remove current handler.
! 1232: If the handler is removed, all pending exceptions are discarded
! 1233: and all exception_wait() are canceled.
! 1234: Only one exception handler can be set per task. If the previous
! 1235: handler exists in task, exception_setup() just overwrite the handler.
! 1236: <br><br>
! 1237: The exception handler must have the following arguments.<br>
! 1238: <br>
! 1239: void exception_handler(int excpt, void *regs);<br>
! 1240: <br>
! 1241: <i>excpt</i> is an exception number, and <i>regs</i> are the machine
! 1242: dependent registers. The exception handler must call the exception_return()
! 1243: function after it processes the exception.
! 1244:
! 1245: <h3>ERRORS</h3>
! 1246: <dl>
! 1247: <dt>[EFAULT]</dt>
! 1248: <dd>The address of <i>handler</i> is inaccessible.</dd>
! 1249: </dl>
! 1250: <br>
! 1251: <hr size="1">
! 1252:
! 1253:
! 1254: <h3 id="ex1">NAME</h3>
! 1255: exception_return() - return from exception handler
! 1256:
! 1257: <h3>SYNOPSIS</h3>
! 1258: <pre>
! 1259: int exception_return(void *regs);
! 1260: </pre>
! 1261:
! 1262: <h3>DESCRIPTION</h3>
! 1263: The exception_return() function is used to return from the exception
! 1264: handler. <i>regs</i> argument must be the same value which is passed
! 1265: to the handler.
! 1266:
! 1267: <h3>ERRORS</h3>
! 1268: <dl>
! 1269: <dt>[EFAULT]</dt>
! 1270: <dd>The address of <i>regs</i> is inaccessible.</dd>
! 1271: </dl>
! 1272: <br>
! 1273: <hr size="1">
! 1274:
! 1275:
! 1276: <h3 id="ex2">NAME</h3>
! 1277: exception_raise() - raise an exception
! 1278:
! 1279: <h3>SYNOPSIS</h3>
! 1280: <pre>
! 1281: int exception_raise(task_t task, int excpt);
! 1282: </pre>
! 1283:
! 1284: <h3>DESCRIPTION</h3>
! 1285: The exception_raise() function raises an exception for the specified task.
! 1286:
! 1287: <h3>ERRORS</h3>
! 1288: <dl>
! 1289: <dt>[ESRCH]</dt>
! 1290: <dd>The specified <i>task</i> is not a valid task ID.</dd>
! 1291: <dt>[EINVAL]</dt>
! 1292: <dd>The specified <i>excpt</i> is not a valid exception.</dd>
! 1293: <dt>[EPERM]</dt>
! 1294: <dd><i>task</i> is a kernel task, or the task does not register an
! 1295: exception handler.
! 1296: <dt>[EPERM]</dt>
! 1297: <dd>The specified <i>task</i> is not a current task, but the caller
! 1298: task does not have CAP_KILL capability.</dd>
! 1299: </dl>
! 1300: <br>
! 1301: <hr size="1">
! 1302:
! 1303:
! 1304: <h3 id="ex3">NAME</h3>
! 1305: exception_wait() - wait an exception
! 1306:
! 1307: <h3>SYNOPSIS</h3>
! 1308: <pre>
! 1309: int exception_wait(int *excpt);
! 1310: </pre>
! 1311:
! 1312: <h3>DESCRIPTION</h3>
! 1313: The exception_wait() function blocks the caller thread until
! 1314: any exception is raised to the thread.
! 1315: <br><br>
! 1316: This routine returns EINTR on success.
! 1317:
! 1318: <h3>ERRORS</h3>
! 1319: <dl>
! 1320: <dt>[EFAULT]</dt>
! 1321: <dd>The address of <i>excpt</i> is inaccessible.</dd>
! 1322: <dt>[EINVAL]</dt>
! 1323: <dd>The caller thread does not register an exception handler.</dd>
! 1324: </dl>
! 1325: <br>
! 1326:
! 1327:
! 1328: <h2 id="dev">Device</h2>
! 1329:
! 1330: <h3 id="dev0">NAME</h3>
! 1331: device_open() - open a device
! 1332:
! 1333: <h3>SYNOPSIS</h3>
! 1334: <pre>
! 1335: int device_open(const char *name, int mode, device_t *dev);
! 1336: </pre>
! 1337:
! 1338: <h3>DESCRIPTION</h3>
! 1339: The device_open() function opens the specified device.
! 1340: <i>mode</i> is one of the following open mode.
! 1341: <ul>
! 1342: <li>O_RDONLY - Read only</li>
! 1343: <li>O_WRONLY - Write only</li>
! 1344: <li>O_RDWR - Read & Write</li>
! 1345: </ul>
! 1346: The ID of the opened device is stored in <i>dev</i> on success.
! 1347:
! 1348: <h3>ERRORS</h3>
! 1349: <dl>
! 1350: <dt>[EFAULT]</dt>
! 1351: <dd>The address of <i>name</i> is inaccessible.</dd>
! 1352: <dt>[ENAMETOOLONG]</dt>
! 1353: <dd>The length of the <i>name</i> argument exceeds MAX_DEVNAME.</dd>
! 1354: <dt>[ENOENT]</dt>
! 1355: <dd>The length of the <i>name</i> argument is 0.</dd>
! 1356: <dt>[ENXIO]</dt>
! 1357: <dd>The device was not found.</dd>
! 1358: <dt>[EPERM]</dt>
! 1359: <dd>The caller task does not have CAP_DEVIO capability.</dd>
! 1360: </dl>
! 1361: Other device specific error may be returned.
! 1362: <br><br>
! 1363: <hr size="1">
! 1364:
! 1365:
! 1366: <h3 id="dev1">NAME</h3>
! 1367: device_close() - close a device
! 1368:
! 1369: <h3>SYNOPSIS</h3>
! 1370: <pre>
! 1371: int device_close(device_t dev);
! 1372: </pre>
! 1373:
! 1374: <h3>DESCRIPTION</h3>
! 1375: The device_close() function close the specified device.
! 1376:
! 1377: <h3>ERRORS</h3>
! 1378: <dl>
! 1379: <dt>[ENODEV]</dt>
! 1380: <dd>The specified device is not valid device.</dd>
! 1381: <dt>[EBADF]</dt>
! 1382: <dd>The specified device is not a valid device opened.</dd>
! 1383: <dt>[EPERM]</dt>
! 1384: <dd>The caller task does not have CAP_DEVIO capability.</dd>
! 1385: </dl>
! 1386: Other device specific error may be returned.
! 1387: <br><br>
! 1388: <hr size="1">
! 1389:
! 1390:
! 1391: <h3 id="dev2">NAME</h3>
! 1392: device_read() - read from a device
! 1393:
! 1394: <h3>SYNOPSIS</h3>
! 1395: <pre>
! 1396: int device_read(device_t dev, void *buf, size_t *nbyte, int blkno);
! 1397: </pre>
! 1398:
! 1399: <h3>DESCRIPTION</h3>
! 1400: The device_read() function reads data from the specified device.
! 1401: <i>nbyte</i> is a read size in byte, and <i>blkno</i> is a start block
! 1402: of the target device. The unit of <i>blkno</i> is device specific.
! 1403:
! 1404: <h3>ERRORS</h3>
! 1405: <dl>
! 1406: <dt>[ENODEV]</dt>
! 1407: <dd>The specified device is not valid device.</dd>
! 1408: <dt>[EBADF]</dt>
! 1409: <dd>The specified device is not a valid device opened for read.</dd>
! 1410: <dt>[EFAULT]</dt>
! 1411: <dd>The specified buffer is inaccessible, or not writable.</dd>
! 1412: <dt>[EPERM]</dt>
! 1413: <dd>The caller task does not have CAP_DEVIO capability.</dd>
! 1414: </dl>
! 1415: Other device specific error may be returned.
! 1416: <br><br>
! 1417: <hr size="1">
! 1418:
! 1419:
! 1420: <h3 id="dev3">NAME</h3>
! 1421: device_write() - write to a device
! 1422:
! 1423: <h3>SYNOPSIS</h3>
! 1424: <pre>
! 1425: int device_write(device_t dev, void *buf, size_t *nbyte, int blkno);
! 1426: </pre>
! 1427:
! 1428: <h3>DESCRIPTION</h3>
! 1429: The device_read() function writes data to the specified device.
! 1430: <i>nbytes</i> is a write size in byte, and <i>blkno</i> is a start block
! 1431: of the target device. The unit of <i>blkno</i> is device specific.
! 1432:
! 1433: <h3>ERRORS</h3>
! 1434: <dl>
! 1435: <dt>[ENODEV]</dt>
! 1436: <dd>The specified device is not valid device.</dd>
! 1437: <dt>[EBADF]</dt>
! 1438: <dd>The specified device is not a valid device opened for write.</dd>
! 1439: <dt>[EFAULT]</dt>
! 1440: <dd>The specified buffer is inaccessible</dd>
! 1441: <dt>[EPERM]</dt>
! 1442: <dd>The caller task does not have CAP_DEVIO capability.</dd>
! 1443: </dl>
! 1444: Other device specific error may be returned.
! 1445: <br><br>
! 1446: <hr size="1">
! 1447:
! 1448:
! 1449: <h3 id="dev4">NAME</h3>
! 1450: device_ioctl() - control a device
! 1451:
! 1452: <h3>SYNOPSIS</h3>
! 1453: <pre>
! 1454: int device_ioctl(device_t dev, int cmd, u_long arg);
! 1455: </pre>
! 1456:
! 1457: <h3>DESCRIPTION</h3>
! 1458: The device_ioctl() function sends a command to the specified device.
! 1459: <i>cmd</i> and <i>arg</i> are device dependent.
! 1460:
! 1461: <h3>ERRORS</h3>
! 1462: <dl>
! 1463: <dt>[ENODEV]</dt>
! 1464: <dd>The specified device is not valid device.</dd>
! 1465: <dt>[EBADF]</dt>
! 1466: <dd>The specified device is not a valid device opened for ioctl.</dd>
! 1467: <dt>[EPERM]</dt>
! 1468: <dd>The caller task does not have CAP_DEVIO capability.</dd>
! 1469: </dl>
! 1470: <br>
! 1471:
! 1472:
! 1473:
! 1474: <h2 id="mu">Mutex</h2>
! 1475:
! 1476: <h3 id="mu0">NAME</h3>
! 1477: mutex_init() - initialize a mutex
! 1478:
! 1479: <h3>SYNOPSIS</h3>
! 1480: <pre>
! 1481: int mutex_init(mutex_t *mu);
! 1482: </pre>
! 1483:
! 1484: <h3>DESCRIPTION</h3>
! 1485: The mutex_init() function creates a new mutex and initializes it.
! 1486: The ID of the new mutex is stored in <i>mu</i> on success.
! 1487: <br><br>
! 1488: If an initialized mutex is reinitialized, undefined behavior results.
! 1489:
! 1490: <h3>ERRORS</h3>
! 1491: <dl>
! 1492: <dt>[ENOMEM]</dt>
! 1493: <dd>The system is unable to allocate resources.</dd>
! 1494: <dt>[EFAULT]</dt>
! 1495: <dd>The address of <i>mu</i> is inaccessible.</dd>
! 1496: </dl>
! 1497: <br>
! 1498: <hr size="1">
! 1499:
! 1500:
! 1501: <h3 id="mu1">NAME</h3>
! 1502: mutex_destroy() - destroy a mutex
! 1503:
! 1504: <h3>SYNOPSIS</h3>
! 1505: <pre>
! 1506: int mutex_destroy(mutex_t *mu);
! 1507: </pre>
! 1508:
! 1509: <h3>DESCRIPTION</h3>
! 1510: The mutex_destroy() function destroys the specified mutex.
! 1511: The mutex must be unlock state, otherwise it fails with EBUSY.
! 1512:
! 1513: <h3>ERRORS</h3>
! 1514: <dl>
! 1515: <dt>[EINVAL]</dt>
! 1516: <dd>The specified mutex is not a valid mutex.</dd>
! 1517: <dt>[EBUSY]</dt>
! 1518: <dd>The mutex is still locked by some thread.</dd>
! 1519: </dl>
! 1520: <br>
! 1521: <hr size="1">
! 1522:
! 1523:
! 1524: <h3 id="mu2">NAME</h3>
! 1525: mutex_trylock() - try to lock a mutex
! 1526:
! 1527: <h3>SYNOPSIS</h3>
! 1528: <pre>
! 1529: int mutex_trylock(mutex_t *mu);
! 1530: </pre>
! 1531:
! 1532: <h3>DESCRIPTION</h3>
! 1533: The mutex_trylock() tries to lock a mutex without blocking.
! 1534:
! 1535: <h3>ERRORS</h3>
! 1536: <dl>
! 1537: <dt>[EINVAL]</dt>
! 1538: <dd>The specified mutex is not a valid mutex.</dd>
! 1539: <dt>[EBUSY]</dt>
! 1540: <dd>The mutex is already locked.</dd>
! 1541: </dl>
! 1542: <br>
! 1543: <hr size="1">
! 1544:
! 1545:
! 1546: <h3 id="mu3">NAME</h3>
! 1547: mutex_lock() - lock a mutex
! 1548:
! 1549: <h3>SYNOPSIS</h3>
! 1550: <pre>
! 1551: int mutex_lock(mutex_t *mu);
! 1552: </pre>
! 1553:
! 1554: <h3>DESCRIPTION</h3>
! 1555: The mutex_lock() locks the specified mutex.
! 1556: The caller thread is blocked if the mutex has already been locked.
! 1557: If the caller thread receives any exception while waiting a mutex,
! 1558: this routine returns with EINTR.
! 1559: The mutex is "recursive". It means a thread can lock the same mutex
! 1560: any number of times.
! 1561: <h3>ERRORS</h3>
! 1562: <dl>
! 1563: <dt>[EINVAL]</dt>
! 1564: <dd>The specified mutex is not a valid mutex.</dd>
! 1565: <dt>[EINTR]</dt>
! 1566: <dd>The function was interrupted by an exception.</dd>
! 1567: </dl>
! 1568: <br>
! 1569: <hr size="1">
! 1570:
! 1571:
! 1572: <h3 id="mu4">NAME</h3>
! 1573: mutex_unlock() - unlock a mutex
! 1574:
! 1575: <h3>SYNOPSIS</h3>
! 1576: <pre>
! 1577: int mutex_unlock(mutex_t *mu);
! 1578: </pre>
! 1579:
! 1580: <h3>DESCRIPTION</h3>
! 1581: The mutex_unlock() function unlocks the specified mutex.
! 1582: The caller thread must be the current mutex owner.
! 1583:
! 1584: <h3>ERRORS</h3>
! 1585: <dl>
! 1586: <dt>[EINVAL]</dt>
! 1587: <dd>The specified mutex is not a valid mutex.</dd>
! 1588: <dt>[EPERM]</dt>
! 1589: <dd>The caller thread is not the mutex owner.</dd>
! 1590: </dl>
! 1591: <br>
! 1592:
! 1593:
! 1594:
! 1595: <h2 id="cv">Condition Variable</h2>
! 1596:
! 1597: <h3 id="cv0">NAME</h3>
! 1598: cond_init() - initialize a condition variable
! 1599:
! 1600: <h3>SYNOPSIS</h3>
! 1601: <pre>
! 1602: int cond_init(cond_t *cond);
! 1603: </pre>
! 1604:
! 1605: <h3>DESCRIPTION</h3>
! 1606: The cond_init() function creates a new condition variable and initializes it.
! 1607: <br><br>
! 1608: If an initialized condition variable is reinitialized, undefined behavior results.
! 1609:
! 1610: <h3>ERRORS</h3>
! 1611: <dl>
! 1612: <dt>[EFAULT]</dt>
! 1613: <dd>The address of <i>cond</i> is inaccessible.</dd>
! 1614: <dt>[ENOMEM]</dt>
! 1615: <dd>The system is unable to allocate resources.</dd>
! 1616: </dl>
! 1617: <br>
! 1618: <hr size="1">
! 1619:
! 1620:
! 1621: <h3 id="cv1">NAME</h3>
! 1622: cond_destroy() - destroy a condition variable
! 1623:
! 1624: <h3>SYNOPSIS</h3>
! 1625: <pre>
! 1626: int cond_destroy(cond_t *cond);
! 1627: </pre>
! 1628:
! 1629: <h3>DESCRIPTION</h3>
! 1630: The cond_destroy() function destroys the specified condition variable.
! 1631: If there are any blocked thread waiting for the specified CV, it
! 1632: returns EBUSY.
! 1633:
! 1634: <h3>ERRORS</h3>
! 1635: <dl>
! 1636: <dt>[EINVAL]</dt>
! 1637: <dd>The specified condition variable is not valid.</dd>
! 1638: <dt>[EBUSY]</dt>
! 1639: <dd>The condition variable is still locked by some thread.</dd>
! 1640: </dl>
! 1641: <br>
! 1642: <hr size="1">
! 1643:
! 1644:
! 1645: <h3 id="cv2">NAME</h3>
! 1646: cond_wait() - wait on a condition
! 1647:
! 1648: <h3>SYNOPSIS</h3>
! 1649: <pre>
! 1650: int cond_wait(cond_t *cond, mutex_t *mu);
! 1651: </pre>
! 1652:
! 1653: <h3>DESCRIPTION</h3>
! 1654: The cond_wait() function waits on the specified condition.
! 1655: If the caller thread receives any exception, this routine returns
! 1656: with EINTR.
! 1657:
! 1658: <h3>ERRORS</h3>
! 1659: <dl>
! 1660: <dt>[EINVAL]</dt>
! 1661: <dd>The specified condition variable is not valid.</dd>
! 1662: <dt>[EINTR]</dt>
! 1663: <dd>The function was interrupted by an exception.</dd>
! 1664: </dl>
! 1665: <br>
! 1666: <hr size="1">
! 1667:
! 1668:
! 1669: <h3 id="cv3">NAME</h3>
! 1670: cond_signal() - signal condition
! 1671:
! 1672: <h3>SYNOPSIS</h3>
! 1673: <pre>
! 1674: int cond_signal(cond_t *cond);
! 1675: </pre>
! 1676:
! 1677: <h3>DESCRIPTION</h3>
! 1678: The cond_signal() function unblocks the thread that is waiting
! 1679: on the specified condition variable.
! 1680:
! 1681: <h3>ERRORS</h3>
! 1682: <dl>
! 1683: <dt>[EINVAL]</dt>
! 1684: <dd>The specified condition variable is not valid.</dd>
! 1685: </dl>
! 1686: <br>
! 1687: <hr size="1">
! 1688:
! 1689:
! 1690: <h3 id="cv4">NAME</h3>
! 1691: cond_broadcast() - broadcast a condition
! 1692:
! 1693: <h3>SYNOPSIS</h3>
! 1694: <pre>
! 1695: int cond_broadcast(cond_t *cond);
! 1696: </pre>
! 1697:
! 1698: <h3>DESCRIPTION</h3>
! 1699: The cond_broadcast() function unblocks all threads that are blocked
! 1700: on the specified condition variable.
! 1701:
! 1702: <h3>ERRORS</h3>
! 1703: <dl>
! 1704: <dt>[EINVAL]</dt>
! 1705: <dd>The specified condition variable is not valid.</dd>
! 1706: </dl>
! 1707: <br>
! 1708:
! 1709:
! 1710:
! 1711: <h2 id="sem">Semaphore</h2>
! 1712:
! 1713: <h3 id="sem0">NAME</h3>
! 1714: sem_init() - initialize a semaphore
! 1715:
! 1716: <h3>SYNOPSIS</h3>
! 1717: <pre>
! 1718: int sem_init(sem_t *sem, u_int value);
! 1719: </pre>
! 1720:
! 1721: <h3>DESCRIPTION</h3>
! 1722: The sem_init() function initializes a semaphore. It will create a
! 1723: new semaphore if the specified <i>sem</i> does not exist. If the
! 1724: specified semaphore <i>sem</i> already exists, it is re-initialized
! 1725: only if nobody is waiting for it.
! 1726: The initial semaphore value is set to <i>value</i> value.
! 1727: The ID of the new semaphore is stored in <i>sem</i> on success.
! 1728:
! 1729: <h3>ERRORS</h3>
! 1730: <dl>
! 1731: <dt>[EINVAL]</dt>
! 1732: <dd><i>value</i> value is larger than SEM_MAX.</dd>
! 1733: <dt>[ENOSPC]</dt>
! 1734: <dd>The system is unable to allocate resources.</dd>
! 1735: <dt>[EFAULT]</dt>
! 1736: <dd>The address of <i>sem</i> is inaccessible.</dd>
! 1737: <dt>[EBUSY]</dt>
! 1738: <dd>There are currently threads blocked on the semaphore.</dd>
! 1739: <dt>[EPERM]</dt>
! 1740: <dd>The caller task is not an owner of the <i>sem</i>, but it
! 1741: does not have CAP_SEMAPHORE capability.</dd>
! 1742: </dl>
! 1743: <br>
! 1744: <hr size="1">
! 1745:
! 1746:
! 1747: <h3 id="sem1">NAME</h3>
! 1748: sem_destroy() - destroy a semaphore
! 1749:
! 1750: <h3>SYNOPSIS</h3>
! 1751: <pre>
! 1752: int sem_destroy(sem_t *sem);
! 1753: </pre>
! 1754:
! 1755: <h3>DESCRIPTION</h3>
! 1756: The sem_destroy() function destroys the specified semaphore.
! 1757: If some thread is waiting for the specified semaphore, this routine
! 1758: fails with EBUSY.
! 1759:
! 1760: <h3>ERRORS</h3>
! 1761: <dl>
! 1762: <dt>[EINVAL]</dt>
! 1763: <dd>The specified semaphore is not a valid semaphore.</dd>
! 1764: <dt>[EBUSY]</dt>
! 1765: <dd>There are currently threads blocked on the semaphore.</dd>
! 1766: </dl>
! 1767: <br>
! 1768: <hr size="1">
! 1769:
! 1770:
! 1771: <h3 id="sem2">NAME</h3>
! 1772: sem_wait() - lock a semaphore
! 1773:
! 1774: <h3>SYNOPSIS</h3>
! 1775: <pre>
! 1776: int sem_wait(sem_t *sem, u_long timeout);
! 1777: </pre>
! 1778:
! 1779: <h3>DESCRIPTION</h3>
! 1780: The sem_wait() function locks the semaphore referred by <i>sem</i>
! 1781: only if the semaphore value is currently positive. The thread
! 1782: will sleep while the semaphore value is zero.
! 1783: It decrements the semaphore value in return.
! 1784: If <i>timeout</i> value is set if it is not 0.
! 1785:
! 1786: <h3>ERRORS</h3>
! 1787: <dl>
! 1788: <dt>[EINVAL]</dt>
! 1789: <dd>The specified semaphore is not a valid semaphore.</dd>
! 1790: <dt>[ETIMEDOUT]</dt>
! 1791: <dd>Time out.</dd>
! 1792: <dt>[EINTR]</dt>
! 1793: <dd>The function was interrupted by an exception.</dd>
! 1794: <dt>[EPERM]</dt>
! 1795: <dd>The caller task is not an owner of the <i>sem</i>, but it
! 1796: does not have CAP_SEMAPHORE capability.</dd>
! 1797: </dl>
! 1798: <br>
! 1799: <hr size="1">
! 1800:
! 1801:
! 1802: <h3 id="sem3">NAME</h3>
! 1803: sem_trywait() - try to lock a semaphore
! 1804:
! 1805: <h3>SYNOPSIS</h3>
! 1806: <pre>
! 1807: int sem_trywait(sem_t *sem);
! 1808: </pre>
! 1809:
! 1810: <h3>DESCRIPTION</h3>
! 1811: The sem_trylock() tries to lock a semaphore without blocking.
! 1812:
! 1813: <h3>ERRORS</h3>
! 1814: <dl>
! 1815: <dt>[EINVAL]</dt>
! 1816: <dd>The specified semaphore is not a valid semaphore.</dd>
! 1817: <dt>[EAGAIN]</dt>
! 1818: <dd>The semaphore is already locked.</dd>
! 1819: <dt>[EPERM]</dt>
! 1820: <dd>The caller task is not an owner of the <i>sem</i>, but it
! 1821: does not have CAP_SEMAPHORE capability.</dd>
! 1822: </dl>
! 1823: <br>
! 1824: <hr size="1">
! 1825:
! 1826:
! 1827: <h3 id="sem4">NAME</h3>
! 1828: sem_post() - unlock a semaphore
! 1829:
! 1830: <h3>SYNOPSIS</h3>
! 1831: <pre>
! 1832: int sem_post(sem_t *sem);
! 1833: </pre>
! 1834:
! 1835: <h3>DESCRIPTION</h3>
! 1836: The sem_post() function unlock the specified semaphore.
! 1837: It increments the semaphore value.
! 1838: If the semaphore value becomes positive, one of the threads waiting
! 1839: to lock will be unblocked.
! 1840: The caller thread is not blocked by this function.
! 1841:
! 1842: <h3>ERRORS</h3>
! 1843: <dl>
! 1844: <dt>[EINVAL]</dt>
! 1845: <dd>The specified semaphore is not a valid semaphore.</dd>
! 1846: <dt>[ERANGE]</dt>
! 1847: <dd>The semaphore value exceeds SEM_MAX.</dd>
! 1848: <dt>[EPERM]</dt>
! 1849: <dd>The caller task is not an owner of the <i>sem</i>, but it
! 1850: does not have CAP_SEMAPHORE capability.</dd>
! 1851: </dl>
! 1852: <br>
! 1853: <hr size="1">
! 1854:
! 1855:
! 1856: <h3 id="sem5">NAME</h3>
! 1857: sem_getvalue() - get the value of a semaphore
! 1858:
! 1859: <h3>SYNOPSIS</h3>
! 1860: <pre>
! 1861: int sem_getvalue(sem_t *sem, u_int *value);
! 1862: </pre>
! 1863:
! 1864: <h3>DESCRIPTION</h3>
! 1865: The sem_getvalue() function returns the current value of the specified semaphore.
! 1866:
! 1867: <h3>ERRORS</h3>
! 1868: <dl>
! 1869: <dt>[EINVAL]</dt>
! 1870: <dd>The specified semaphore is not a valid semaphore.</dd>
! 1871: <dt>[EFAULT]</dt>
! 1872: <dd>The address of <i>sem</i> is inaccessible.</dd>
! 1873: <dt>[EPERM]</dt>
! 1874: <dd>The caller task is not an owner of the <i>sem</i>, but it
! 1875: does not have CAP_SEMAPHORE capability.</dd>
! 1876: </dl>
! 1877: <br>
! 1878:
! 1879:
! 1880:
! 1881: <h2 id="sys">System</h2>
! 1882:
! 1883: <h3 id="sys0">NAME</h3>
! 1884: sys_log() - log a message
! 1885:
! 1886: <h3>SYNOPSIS</h3>
! 1887: <pre>
! 1888: void sys_log(const char *buf);
! 1889: </pre>
! 1890:
! 1891: <h3>DESCRIPTION</h3>
! 1892: The sys_log() function puts the specified text message to the
! 1893: predefined device.
! 1894: This function is available only when the kernel is built with debug flag.
! 1895:
! 1896: <h3>ERRORS</h3>
! 1897: <dl>
! 1898: <dt>[EINVAL]</dt>
! 1899: <dd>The message is too long.</dd>
! 1900: <dt>[EFAULT]</dt>
! 1901: <dd>The address of <i>buf</i> is inaccessible.</dd>
! 1902: </dl>
! 1903: <br>
! 1904: <hr size="1">
! 1905:
! 1906:
! 1907: <h3 id="sys1">NAME</h3>
! 1908: sys_panic() - fatal error
! 1909:
! 1910: <h3>SYNOPSIS</h3>
! 1911: <pre>
! 1912: void sys_panic(const char *buf);
! 1913: </pre>
! 1914:
! 1915: <h3>DESCRIPTION</h3>
! 1916: The sys_panic() function shows the panic message and stops the system.
! 1917: The application should use this call only when it detects the unrecoverable
! 1918: error.
! 1919:
! 1920: <h3>ERRORS</h3>
! 1921: No errors are defined.
! 1922: <br>
! 1923: <br>
! 1924: <hr size="1">
! 1925:
! 1926:
! 1927:
! 1928: <h3 id="sys2">NAME</h3>
! 1929: sys_info() - return system information
! 1930:
! 1931: <h3>SYNOPSIS</h3>
! 1932: <pre>
! 1933: int sys_info(int type, void *buf);
! 1934: </pre>
! 1935:
! 1936: <h3>DESCRIPTION</h3>
! 1937: The sys_info() function returns the specified system information.
! 1938: The kernel supports the following system infomation.
! 1939: <ul>
! 1940: <li>INFO_KERNEL - Get kernel information</li>
! 1941: <li>INFO_MEMORY - Get memory information</li>
! 1942: <li>INFO_SCHED - Get scheduling information</li>
! 1943: <li>INFO_THREAD - Get thread information</li>
! 1944: <li>INFO_DEVICE - Get device information</li>
! 1945: </ul>
! 1946:
! 1947: <h3>ERRORS</h3>
! 1948: <dl>
! 1949: <dt>[EINVAL]</dt>
! 1950: <dd><i>type</i> is not a valid type.</dd>
! 1951: <dt>[EFAULT]</dt>
! 1952: <dd>The address of <i>buf</i> is inaccessible.</dd>
! 1953: </dl>
! 1954: <br>
! 1955: <hr size="1">
! 1956:
! 1957:
! 1958:
! 1959: <h3 id="sys3">NAME</h3>
! 1960: sys_time() - return system ticks
! 1961:
! 1962: <h3>SYNOPSIS</h3>
! 1963: <pre>
! 1964: int sys_time(u_long *ticks);
! 1965: </pre>
! 1966:
! 1967: <h3>DESCRIPTION</h3>
! 1968: The sys_time() function returns the current system ticks.
! 1969:
! 1970: <h3>ERRORS</h3>
! 1971: <dl>
! 1972: <dt>[EFAULT]</dt>
! 1973: <dd>The address of <i>ticks</i> is inaccessible.</dd>
! 1974: </dl>
! 1975: <br>
! 1976: <hr size="1">
! 1977:
! 1978:
! 1979:
! 1980: <h3 id="sys4">NAME</h3>
! 1981: sys_debug() - kernel debugging interface
! 1982:
! 1983: <h3>SYNOPSIS</h3>
! 1984: <pre>
! 1985: int sys_debug(int cmd, int param);
! 1986: </pre>
! 1987:
! 1988: <h3>DESCRIPTION</h3>
! 1989: The sys_debug() controls the kernel built-in debug functions.
! 1990: The kernel supports the following commands.
! 1991: <ul>
! 1992: <li>DBGCMD_DUMP - Dump kernel information</li>
! 1993: </ul>
! 1994:
! 1995: <h3>ERRORS</h3>
! 1996: <dl>
! 1997: <dt>[EINVAL]</dt>
! 1998: <dd><i>cmd</i> is not a valid command.</dd>
! 1999: <dt>[ENOSYS]</dt>
! 2000: <dd>The function is not supported.</dd>
! 2001: </dl>
! 2002: <br>
! 2003:
! 2004: </td>
! 2005: </tr>
! 2006: <tr>
! 2007: <td id="footer" colspan="2" style="vertical-align: top;">
! 2008: <a href="http://sourceforge.net">
! 2009: <img src="http://sourceforge.net/sflogo.php?group_id=132028&type=1"
! 2010: alt="SourceForge.net Logo" border="0" height="31" width="88"></a><br>
! 2011: Copyright© 2005-2007 Kohsuke Ohtani
! 2012: </td>
! 2013: </tr>
! 2014:
! 2015: </tbody>
! 2016: </table>
! 2017:
! 2018: </div>
! 2019: <div id="bottom"></div>
! 2020:
! 2021: </body>
! 2022: </html>
CVSweb
![[BACK]](/icons/back.gif){kind=icon}
Return to kapi.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / prex-old / doc / html / doc