1
0

object 3.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150
  1. .TH OBJECT 2
  2. .SH NAME
  3. objtype, readobj, objtraverse, isar, nextar, readar \- object file interpretation functions
  4. .SH SYNOPSIS
  5. .B #include <u.h>
  6. .br
  7. .B #include <libc.h>
  8. .br
  9. .B #include <bio.h>
  10. .br
  11. .B #include <mach.h>
  12. .PP
  13. .ta \w'\fLmachines 'u
  14. .B
  15. int objtype(Biobuf *bp, char **name)
  16. .PP
  17. .B
  18. int readobj(Biobuf *bp, int objtype)
  19. .PP
  20. .B
  21. void objtraverse(void(*)(Sym*, void*), void*)
  22. .PP
  23. .B
  24. int isar(Biobuf *bp)
  25. .PP
  26. .B
  27. int nextar(Biobuf *bp, int offset, char *buf)
  28. .PP
  29. .B
  30. int readar(Biobuf *bp, int objtype, int end)
  31. .SH DESCRIPTION
  32. These functions provide machine-independent access to object files
  33. in a directory or an archive.
  34. .IR Mach (2)
  35. and
  36. .IR symbol (2)
  37. describe additional library functions
  38. for interpreting executable files and executing images.
  39. .PP
  40. Object files contain no formal symbol table; instead, references
  41. to symbols must be extracted from the encoded object representation
  42. and resolved. The resulting symbol information is loaded
  43. into a dummy symbol table where it is available for processing by an
  44. application. The organization of the dummy symbol
  45. table is identical
  46. to that produced by the loader and described in
  47. .IR symbol (2)
  48. and
  49. .IR a.out (6):
  50. a vector of
  51. .B Sym
  52. data structures defining the name, type and relative offset of
  53. each symbol.
  54. .PP
  55. .I Objtype
  56. reads the header at the current position of the
  57. file associated with
  58. .I bp
  59. (see
  60. .IR Bio (2))
  61. to see if it is an intermediate object file.
  62. If it is, a code indicating the architecture type of the file
  63. is returned and the second argument, if it is non-zero,
  64. is set pointing to a string describing the type of the file.
  65. If the header does not indicate an object file,
  66. \-1 is returned.
  67. The header may be at the start of an object
  68. file or at the beginning of an archive member. The
  69. file is rewound to its starting
  70. position after decoding the header.
  71. .PP
  72. .I Readobj
  73. constructs a symbol table for the object file associated with
  74. .IR bp .
  75. The second argument contains the type code produced by
  76. function
  77. .IR objtype .
  78. The file must be positioned at the start of the object file.
  79. Each invocation of
  80. .I readobj
  81. destroys the symbol definitions for any previous file.
  82. .PP
  83. .I Objtraverse
  84. scans the symbol table previously built by
  85. .I readobj
  86. or
  87. .IR readar .
  88. .I Objtraverse
  89. requires two arguments:
  90. the address of a call-back function and a
  91. generic pointer. The call-back function
  92. is invoked once for each symbol in the symbol table with
  93. the address of a
  94. .I Sym
  95. data structure as the first argument and the
  96. generic pointer as the second.
  97. .PP
  98. .I Isar
  99. reads the header at the current point in the file
  100. associated with
  101. .I bp
  102. and returns 1 if it is an archive or zero otherwise.
  103. The file is positioned at the end of the archive
  104. header and at the beginning of the first member of the archive.
  105. .PP
  106. .I Nextar
  107. extracts information describing the archive member stored
  108. at
  109. .I offset
  110. in the file associated with
  111. .IR bp .
  112. If the header describing the member can be
  113. extracted and decoded, the size of the member is
  114. returned. Adding this value to
  115. .I offset
  116. yields the offset of the beginning of the next member
  117. in the archive. On return the input file is positioned
  118. at the end of the member header
  119. and the name of the member is stored in
  120. .IR buf ,
  121. a buffer of
  122. .B SARNAME
  123. characters.
  124. If there are no more members,
  125. .I nextar
  126. returns zero; a negative return indicates a missing
  127. or malformed header.
  128. .PP
  129. .I Readar
  130. constructs the symbol table of the object file stored
  131. at the current position in the archive associated with
  132. .IR bp .
  133. This function operates exactly as
  134. .IR readobj ;
  135. the only difference is the extra argument,
  136. .IR end ,
  137. specifying the offset to the beginning of the
  138. next member in the archive.
  139. .I Readar
  140. leaves the file positioned at that point.
  141. .SH SOURCE
  142. .B /sys/src/libmach
  143. .SH "SEE ALSO"
  144. .IR mach (2),
  145. .IR symbol (2),
  146. .IR bio (2),
  147. .IR a.out (6)
  148. .SH DIAGNOSTICS
  149. These routines set
  150. .IR errstr .