api-io.texi 80 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914
  1. @c -*-texinfo-*-
  2. @c This is part of the GNU Guile Reference Manual.
  3. @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009,
  4. @c 2010, 2011, 2013, 2016, 2019 Free Software Foundation, Inc.
  5. @c See the file guile.texi for copying conditions.
  6. @node Input and Output
  7. @section Input and Output
  8. @menu
  9. * Ports:: What's a port?
  10. * Binary I/O:: Reading and writing bytes.
  11. * Encoding:: Characters as bytes.
  12. * Textual I/O:: Reading and writing characters.
  13. * Simple Output:: Simple syntactic sugar solution.
  14. * Buffering:: Controlling when data is written to ports.
  15. * Random Access:: Moving around a random access port.
  16. * Line/Delimited:: Read and write lines or delimited text.
  17. * Default Ports:: Defaults for input, output and errors.
  18. * Port Types:: Types of port and how to make them.
  19. * Venerable Port Interfaces:: Procedures from the last millenium.
  20. * Using Ports from C:: Nice interfaces for C.
  21. * I/O Extensions:: Implementing new port types in C.
  22. * Non-Blocking I/O:: How Guile deals with EWOULDBLOCK.
  23. * BOM Handling:: Handling of Unicode byte order marks.
  24. @end menu
  25. @node Ports
  26. @subsection Ports
  27. @cindex Port
  28. Ports are the way that Guile performs input and output. Guile can read
  29. in characters or bytes from an @dfn{input port}, or write them out to an
  30. @dfn{output port}. Some ports support both interfaces.
  31. There are a number of different port types implemented in Guile. File
  32. ports provide input and output over files, as you might imagine. For
  33. example, we might display a string to a file like this:
  34. @example
  35. (let ((port (open-output-file "foo.txt")))
  36. (display "Hello, world!\n" port)
  37. (close-port port))
  38. @end example
  39. There are also string ports, for taking input from a string, or
  40. collecting output to a string; bytevector ports, for doing the same but
  41. using a bytevector as a source or sink of data; and soft ports, for
  42. arranging to call Scheme functions to provide input or handle output.
  43. @xref{Port Types}.
  44. Ports should be @dfn{closed} when they are not needed by calling
  45. @code{close-port} on them, as in the example above. This will make sure
  46. that any pending output is successfully written out to disk, in the case
  47. of a file port, or otherwise to whatever mutable store is backed by the
  48. port. Any error that occurs while writing out that buffered data would
  49. also be raised promptly at the @code{close-port}, and not later when the
  50. port is closed by the garbage collector. @xref{Buffering}, for more on
  51. buffered output.
  52. Closing a port also releases any precious resource the file might have.
  53. Usually in Scheme a programmer doesn't have to clean up after their data
  54. structures (@pxref{Memory Management}), but most systems have strict
  55. limits on how many files can be open, both on a per-process and a
  56. system-wide basis. A program that uses many files should take care not
  57. to hit those limits. The same applies to similar system resources such
  58. as pipes and sockets.
  59. Indeed for these reasons the above example is not the most idiomatic way
  60. to use ports. It is more common to acquire ports via procedures like
  61. @code{call-with-output-file}, which handle the @code{close-port}
  62. automatically:
  63. @example
  64. (call-with-output-file "foo.txt"
  65. (lambda (port)
  66. (display "Hello, world!\n" port)))
  67. @end example
  68. Finally, all ports have associated input and output buffers, as
  69. appropriate. Buffering is a common strategy to limit the overhead of
  70. small reads and writes: without buffering, each character fetched from a
  71. file would involve at least one call into the kernel, and maybe more
  72. depending on the character and the encoding. Instead, Guile will batch
  73. reads and writes into internal buffers. However, sometimes you want to
  74. make output on a port show up immediately. @xref{Buffering}, for more
  75. on interfaces to control port buffering.
  76. @deffn {Scheme Procedure} port? x
  77. @deffnx {C Function} scm_port_p (x)
  78. Return a boolean indicating whether @var{x} is a port.
  79. @end deffn
  80. @rnindex input-port?
  81. @deffn {Scheme Procedure} input-port? x
  82. @deffnx {C Function} scm_input_port_p (x)
  83. Return @code{#t} if @var{x} is an input port, otherwise return
  84. @code{#f}. Any object satisfying this predicate also satisfies
  85. @code{port?}.
  86. @end deffn
  87. @rnindex output-port?
  88. @deffn {Scheme Procedure} output-port? x
  89. @deffnx {C Function} scm_output_port_p (x)
  90. Return @code{#t} if @var{x} is an output port, otherwise return
  91. @code{#f}. Any object satisfying this predicate also satisfies
  92. @code{port?}.
  93. @end deffn
  94. @cindex Closing ports
  95. @cindex Port, close
  96. @deffn {Scheme Procedure} close-port port
  97. @deffnx {C Function} scm_close_port (port)
  98. Close the specified port object. Return @code{#t} if it successfully
  99. closes a port or @code{#f} if it was already closed. An exception may
  100. be raised if an error occurs, for example when flushing buffered output.
  101. @xref{Buffering}, for more on buffered output. @xref{Ports and File
  102. Descriptors, close}, for a procedure which can close file descriptors.
  103. @end deffn
  104. @deffn {Scheme Procedure} port-closed? port
  105. @deffnx {C Function} scm_port_closed_p (port)
  106. Return @code{#t} if @var{port} is closed or @code{#f} if it is
  107. open.
  108. @end deffn
  109. @node Binary I/O
  110. @subsection Binary I/O
  111. Guile's ports are fundamentally binary in nature: at the lowest level,
  112. they work on bytes. This section describes Guile's core binary I/O
  113. operations. @xref{Textual I/O}, for input and output of strings and
  114. characters.
  115. To use these routines, first include the binary I/O module:
  116. @example
  117. (use-modules (ice-9 binary-ports))
  118. @end example
  119. Note that although this module's name suggests that binary ports are
  120. some different kind of port, that's not the case: all ports in Guile are
  121. both binary and textual ports.
  122. @cindex binary input
  123. @deffn {Scheme Procedure} get-u8 port
  124. @deffnx {C Function} scm_get_u8 (port)
  125. Return an octet read from @var{port}, an input port, blocking as
  126. necessary, or the end-of-file object.
  127. @end deffn
  128. @deffn {Scheme Procedure} lookahead-u8 port
  129. @deffnx {C Function} scm_lookahead_u8 (port)
  130. Like @code{get-u8} but does not update @var{port}'s position to point
  131. past the octet.
  132. @end deffn
  133. The end-of-file object is unlike any other kind of object: it's not a
  134. pair, a symbol, or anything else. To check if a value is the
  135. end-of-file object, use the @code{eof-object?} predicate.
  136. @rnindex eof-object?
  137. @cindex End of file object
  138. @deffn {Scheme Procedure} eof-object? x
  139. @deffnx {C Function} scm_eof_object_p (x)
  140. Return @code{#t} if @var{x} is an end-of-file object, or @code{#f}
  141. otherwise.
  142. @end deffn
  143. Note that unlike other procedures in this module, @code{eof-object?} is
  144. defined in the default environment.
  145. @deffn {Scheme Procedure} get-bytevector-n port count
  146. @deffnx {C Function} scm_get_bytevector_n (port, count)
  147. Read @var{count} octets from @var{port}, blocking as necessary and
  148. return a bytevector containing the octets read. If fewer bytes are
  149. available, a bytevector smaller than @var{count} is returned.
  150. @end deffn
  151. @deffn {Scheme Procedure} get-bytevector-n! port bv start count
  152. @deffnx {C Function} scm_get_bytevector_n_x (port, bv, start, count)
  153. Read @var{count} bytes from @var{port} and store them in @var{bv}
  154. starting at index @var{start}. Return either the number of bytes
  155. actually read or the end-of-file object.
  156. @end deffn
  157. @deffn {Scheme Procedure} get-bytevector-some port
  158. @deffnx {C Function} scm_get_bytevector_some (port)
  159. Read from @var{port}, blocking as necessary, until bytes are available
  160. or an end-of-file is reached. Return either the end-of-file object or a
  161. new bytevector containing some of the available bytes (at least one),
  162. and update the port position to point just past these bytes.
  163. @end deffn
  164. @deffn {Scheme Procedure} get-bytevector-some! port bv start count
  165. @deffnx {C Function} scm_get_bytevector_some_x (port, bv, start, count)
  166. Read up to @var{count} bytes from @var{port}, blocking as necessary
  167. until at least one byte is available or an end-of-file is reached.
  168. Store them in @var{bv} starting at index @var{start}. Return the number
  169. of bytes actually read, or an end-of-file object.
  170. @end deffn
  171. @deffn {Scheme Procedure} get-bytevector-all port
  172. @deffnx {C Function} scm_get_bytevector_all (port)
  173. Read from @var{port}, blocking as necessary, until the end-of-file is
  174. reached. Return either a new bytevector containing the data read or the
  175. end-of-file object (if no data were available).
  176. @end deffn
  177. @deffn {Scheme Procedure} unget-bytevector port bv [start [count]]
  178. @deffnx {C Function} scm_unget_bytevector (port, bv, start, count)
  179. Place the contents of @var{bv} in @var{port}, optionally starting at
  180. index @var{start} and limiting to @var{count} octets, so that its bytes
  181. will be read from left-to-right as the next bytes from @var{port} during
  182. subsequent read operations. If called multiple times, the unread bytes
  183. will be read again in last-in first-out order.
  184. @end deffn
  185. @cindex binary output
  186. To perform binary output on a port, use @code{put-u8} or
  187. @code{put-bytevector}.
  188. @deffn {Scheme Procedure} put-u8 port octet
  189. @deffnx {C Function} scm_put_u8 (port, octet)
  190. Write @var{octet}, an integer in the 0--255 range, to @var{port}, a
  191. binary output port.
  192. @end deffn
  193. @deffn {Scheme Procedure} put-bytevector port bv [start [count]]
  194. @deffnx {C Function} scm_put_bytevector (port, bv, start, count)
  195. Write the contents of @var{bv} to @var{port}, optionally starting at
  196. index @var{start} and limiting to @var{count} octets.
  197. @end deffn
  198. @node Encoding
  199. @subsection Encoding
  200. Textual input and output on Guile ports is layered on top of binary
  201. operations. To this end, each port has an associated character encoding
  202. that controls how bytes read from the port are converted to characters,
  203. and how characters written to the port are converted to bytes.
  204. @deffn {Scheme Procedure} port-encoding port
  205. @deffnx {C Function} scm_port_encoding (port)
  206. Returns, as a string, the character encoding that @var{port} uses to
  207. interpret its input and output.
  208. @end deffn
  209. @deffn {Scheme Procedure} set-port-encoding! port enc
  210. @deffnx {C Function} scm_set_port_encoding_x (port, enc)
  211. Sets the character encoding that will be used to interpret I/O to
  212. @var{port}. @var{enc} is a string containing the name of an encoding.
  213. Valid encoding names are those
  214. @url{http://www.iana.org/assignments/character-sets, defined by IANA},
  215. for example @code{"UTF-8"} or @code{"ISO-8859-1"}.
  216. @end deffn
  217. When ports are created, they are assigned an encoding. The usual
  218. process to determine the initial encoding for a port is to take the
  219. value of the @code{%default-port-encoding} fluid.
  220. @defvr {Scheme Variable} %default-port-encoding
  221. A fluid containing name of the encoding to be used by default for newly
  222. created ports (@pxref{Fluids and Dynamic States}). As a special case,
  223. the value @code{#f} is equivalent to @code{"ISO-8859-1"}.
  224. @end defvr
  225. The @code{%default-port-encoding} itself defaults to the encoding
  226. appropriate for the current locale, if @code{setlocale} has been called.
  227. @xref{Locales}, for more on locales and when you might need to call
  228. @code{setlocale} explicitly.
  229. Some port types have other ways of determining their initial locales.
  230. String ports, for example, default to the UTF-8 encoding, in order to be
  231. able to represent all characters regardless of the current locale. File
  232. ports can optionally sniff their file for a @code{coding:} declaration;
  233. @xref{File Ports}. Binary ports might be initialized to the ISO-8859-1
  234. encoding in which each codepoint between 0 and 255 corresponds to a byte
  235. with that value.
  236. Currently, the ports only work with @emph{non-modal} encodings. Most
  237. encodings are non-modal, meaning that the conversion of bytes to a
  238. string doesn't depend on its context: the same byte sequence will always
  239. return the same string. A couple of modal encodings are in common use,
  240. like ISO-2022-JP and ISO-2022-KR, and they are not yet supported.
  241. @cindex port conversion strategy
  242. @cindex conversion strategy, port
  243. @cindex decoding error
  244. @cindex encoding error
  245. Each port also has an associated conversion strategy, which determines
  246. what to do when a Guile character can't be converted to the port's
  247. encoded character representation for output. There are three possible
  248. strategies: to raise an error, to replace the character with a hex
  249. escape, or to replace the character with a substitute character. Port
  250. conversion strategies are also used when decoding characters from an
  251. input port.
  252. @deffn {Scheme Procedure} port-conversion-strategy port
  253. @deffnx {C Function} scm_port_conversion_strategy (port)
  254. Returns the behavior of the port when outputting a character that is not
  255. representable in the port's current encoding.
  256. If @var{port} is @code{#f}, then the current default behavior will be
  257. returned. New ports will have this default behavior when they are
  258. created.
  259. @end deffn
  260. @deffn {Scheme Procedure} set-port-conversion-strategy! port sym
  261. @deffnx {C Function} scm_set_port_conversion_strategy_x (port, sym)
  262. Sets the behavior of Guile when outputting a character that is not
  263. representable in the port's current encoding, or when Guile encounters a
  264. decoding error when trying to read a character. @var{sym} can be either
  265. @code{error}, @code{substitute}, or @code{escape}.
  266. If @var{port} is an open port, the conversion error behavior is set for
  267. that port. If it is @code{#f}, it is set as the default behavior for
  268. any future ports that get created in this thread.
  269. @end deffn
  270. As with port encodings, there is a fluid which determines the initial
  271. conversion strategy for a port.
  272. @deffn {Scheme Variable} %default-port-conversion-strategy
  273. The fluid that defines the conversion strategy for newly created ports,
  274. and also for other conversion routines such as @code{scm_to_stringn},
  275. @code{scm_from_stringn}, @code{string->pointer}, and
  276. @code{pointer->string}.
  277. Its value must be one of the symbols described above, with the same
  278. semantics: @code{error}, @code{substitute}, or @code{escape}.
  279. When Guile starts, its value is @code{substitute}.
  280. Note that @code{(set-port-conversion-strategy! #f @var{sym})} is
  281. equivalent to @code{(fluid-set! %default-port-conversion-strategy
  282. @var{sym})}.
  283. @end deffn
  284. As mentioned above, for an output port there are three possible port
  285. conversion strategies. The @code{error} strategy will throw an error
  286. when a nonconvertible character is encountered. The @code{substitute}
  287. strategy will replace nonconvertible characters with a question mark
  288. (@samp{?}). Finally the @code{escape} strategy will print
  289. nonconvertible characters as a hex escape, using the escaping that is
  290. recognized by Guile's string syntax. Note that if the port's encoding
  291. is a Unicode encoding, like @code{UTF-8}, then encoding errors are
  292. impossible.
  293. For an input port, the @code{error} strategy will cause Guile to throw
  294. an error if it encounters an invalid encoding, such as might happen if
  295. you tried to read @code{ISO-8859-1} as @code{UTF-8}. The error is
  296. thrown before advancing the read position. The @code{substitute}
  297. strategy will replace the bad bytes with a U+FFFD replacement character,
  298. in accordance with Unicode recommendations. When reading from an input
  299. port, the @code{escape} strategy is treated as if it were @code{error}.
  300. @node Textual I/O
  301. @subsection Textual I/O
  302. @cindex textual input
  303. @cindex textual output
  304. This section describes Guile's core textual I/O operations on characters
  305. and strings. @xref{Binary I/O}, for input and output of bytes and
  306. bytevectors. @xref{Encoding}, for more on how characters relate to
  307. bytes. To read general S-expressions from ports, @xref{Scheme Read}.
  308. @xref{Scheme Write}, for interfaces that write generic Scheme datums.
  309. To use these routines, first include the textual I/O module:
  310. @example
  311. (use-modules (ice-9 textual-ports))
  312. @end example
  313. Note that although this module's name suggests that textual ports are
  314. some different kind of port, that's not the case: all ports in Guile are
  315. both binary and textual ports.
  316. @deffn {Scheme Procedure} get-char input-port
  317. Reads from @var{input-port}, blocking as necessary, until a
  318. complete character is available from @var{input-port},
  319. or until an end of file is reached.
  320. If a complete character is available before the next end of file,
  321. @code{get-char} returns that character and updates the input port to
  322. point past the character. If an end of file is reached before any
  323. character is read, @code{get-char} returns the end-of-file object.
  324. @end deffn
  325. @deffn {Scheme Procedure} lookahead-char input-port
  326. The @code{lookahead-char} procedure is like @code{get-char}, but it does
  327. not update @var{input-port} to point past the character.
  328. @end deffn
  329. In the same way that it's possible to "unget" a byte or bytes, it's
  330. possible to "unget" the bytes corresponding to an encoded character.
  331. @deffn {Scheme Procedure} unget-char port char
  332. Place character @var{char} in @var{port} so that it will be read by the
  333. next read operation. If called multiple times, the unread characters
  334. will be read again in last-in first-out order.
  335. @end deffn
  336. @deffn {Scheme Procedure} unget-string port str
  337. Place the string @var{str} in @var{port} so that its characters will
  338. be read from left-to-right as the next characters from @var{port}
  339. during subsequent read operations. If called multiple times, the
  340. unread characters will be read again in last-in first-out order.
  341. @end deffn
  342. Reading in a character at a time can be inefficient. If it's possible
  343. to perform I/O over multiple characters at a time, via strings, that
  344. might be faster.
  345. @deffn {Scheme Procedure} get-string-n input-port count
  346. The @code{get-string-n} procedure reads from @var{input-port}, blocking
  347. as necessary, until @var{count} characters are available, or until an
  348. end of file is reached. @var{count} must be an exact, non-negative
  349. integer, representing the number of characters to be read.
  350. If @var{count} characters are available before end of file,
  351. @code{get-string-n} returns a string consisting of those @var{count}
  352. characters. If fewer characters are available before an end of file, but
  353. one or more characters can be read, @code{get-string-n} returns a string
  354. containing those characters. In either case, the input port is updated
  355. to point just past the characters read. If no characters can be read
  356. before an end of file, the end-of-file object is returned.
  357. @end deffn
  358. @deffn {Scheme Procedure} get-string-n! input-port string start count
  359. The @code{get-string-n!} procedure reads from @var{input-port} in the
  360. same manner as @code{get-string-n}. @var{start} and @var{count} must be
  361. exact, non-negative integer objects, with @var{count} representing the
  362. number of characters to be read. @var{string} must be a string with at
  363. least $@var{start} + @var{count}$ characters.
  364. If @var{count} characters are available before an end of file, they are
  365. written into @var{string} starting at index @var{start}, and @var{count}
  366. is returned. If fewer characters are available before an end of file,
  367. but one or more can be read, those characters are written into
  368. @var{string} starting at index @var{start} and the number of characters
  369. actually read is returned as an exact integer object. If no characters
  370. can be read before an end of file, the end-of-file object is returned.
  371. @end deffn
  372. @deffn {Scheme Procedure} get-string-all input-port
  373. Reads from @var{input-port} until an end of file, decoding characters in
  374. the same manner as @code{get-string-n} and @code{get-string-n!}.
  375. If characters are available before the end of file, a string containing
  376. all the characters decoded from that data are returned. If no character
  377. precedes the end of file, the end-of-file object is returned.
  378. @end deffn
  379. @deffn {Scheme Procedure} get-line input-port
  380. Reads from @var{input-port} up to and including the linefeed
  381. character or end of file, decoding characters in the same manner as
  382. @code{get-string-n} and @code{get-string-n!}.
  383. If a linefeed character is read, a string containing all of the text up
  384. to (but not including) the linefeed character is returned, and the port
  385. is updated to point just past the linefeed character. If an end of file
  386. is encountered before any linefeed character is read, but some
  387. characters have been read and decoded as characters, a string containing
  388. those characters is returned. If an end of file is encountered before
  389. any characters are read, the end-of-file object is returned.
  390. @end deffn
  391. Finally, there are just two core procedures to write characters to a
  392. port.
  393. @deffn {Scheme Procedure} put-char port char
  394. Writes @var{char} to the port. The @code{put-char} procedure returns
  395. an unspecified value.
  396. @end deffn
  397. @deffn {Scheme Procedure} put-string port string
  398. @deffnx {Scheme Procedure} put-string port string start
  399. @deffnx {Scheme Procedure} put-string port string start count
  400. Write the @var{count} characters of @var{string} starting at index
  401. @var{start} to the port.
  402. @var{start} and @var{count} must be non-negative exact integer objects.
  403. @var{string} must have a length of at least @math{@var{start} +
  404. @var{count}}. @var{start} defaults to 0. @var{count} defaults to
  405. @math{@code{(string-length @var{string})} - @var{start}}$.
  406. Calling @code{put-string} is equivalent in all respects to calling
  407. @code{put-char} on the relevant sequence of characters, except that it
  408. will attempt to write multiple characters to the port at a time, even if
  409. the port is unbuffered.
  410. The @code{put-string} procedure returns an unspecified value.
  411. @end deffn
  412. Textual ports have a textual position associated with them: a line and a
  413. column. Reading in characters or writing them out advances the line and
  414. the column appropriately.
  415. @deffn {Scheme Procedure} port-column port
  416. @deffnx {Scheme Procedure} port-line port
  417. @deffnx {C Function} scm_port_column (port)
  418. @deffnx {C Function} scm_port_line (port)
  419. Return the current column number or line number of @var{port}.
  420. @end deffn
  421. Port lines and positions are represented as 0-origin integers, which is
  422. to say that the the first character of the first line is line 0, column
  423. 0. However, when you display a line number, for example in an error
  424. message, we recommend you add 1 to get 1-origin integers. This is
  425. because lines numbers traditionally start with 1, and that is what
  426. non-programmers will find most natural.
  427. @deffn {Scheme Procedure} set-port-column! port column
  428. @deffnx {Scheme Procedure} set-port-line! port line
  429. @deffnx {C Function} scm_set_port_column_x (port, column)
  430. @deffnx {C Function} scm_set_port_line_x (port, line)
  431. Set the current column or line number of @var{port}.
  432. @end deffn
  433. @node Simple Output
  434. @subsection Simple Textual Output
  435. Guile exports a simple formatted output function, @code{simple-format}.
  436. For a more capable formatted output facility, @xref{Formatted Output}.
  437. @deffn {Scheme Procedure} simple-format destination message . args
  438. @deffnx {C Function} scm_simple_format (destination, message, args)
  439. Write @var{message} to @var{destination}, defaulting to the current
  440. output port. @var{message} can contain @code{~A} and @code{~S} escapes.
  441. When printed, the escapes are replaced with corresponding members of
  442. @var{args}: @code{~A} formats using @code{display} and @code{~S} formats
  443. using @code{write}. If @var{destination} is @code{#t}, then use the
  444. current output port, if @var{destination} is @code{#f}, then return a
  445. string containing the formatted text. Does not add a trailing newline.
  446. @end deffn
  447. Somewhat confusingly, Guile binds the @code{format} identifier to
  448. @code{simple-format} at startup. Once @code{(ice-9 format)} loads, it
  449. actually replaces the core @code{format} binding, so depending on
  450. whether you or a module you use has loaded @code{(ice-9 format)}, you
  451. may be using the simple or the more capable version.
  452. @node Buffering
  453. @subsection Buffering
  454. @cindex Port, buffering
  455. Every port has associated input and output buffers. You can think of
  456. ports as being backed by some mutable store, and that store might be far
  457. away. For example, ports backed by file descriptors have to go all the
  458. way to the kernel to read and write their data. To avoid this
  459. round-trip cost, Guile usually reads in data from the mutable store in
  460. chunks, and then services small requests like @code{get-char} out of
  461. that intermediate buffer. Similarly, small writes like
  462. @code{write-char} first go to a buffer, and are sent to the store when
  463. the buffer is full (or when port is flushed). Buffered ports speed up
  464. your program by reducing the number of round-trips to the mutable store,
  465. and they do so in a way that is mostly transparent to the user.
  466. There are two major ways, however, in which buffering affects program
  467. semantics. Building correct, performant programs requires understanding
  468. these situations.
  469. The first case is in random-access read/write ports (@pxref{Random
  470. Access}). These ports, usually backed by a file, logically operate over
  471. the same mutable store when both reading and writing. So, if you read a
  472. character, causing the buffer to fill, then write a character, the bytes
  473. you filled in your read buffer are now invalid. Every time you switch
  474. between reading and writing, Guile has to flush any pending buffer. If
  475. this happens frequently, the cost can be high. In that case you should
  476. reduce the amount that you buffer, in both directions. Similarly, Guile
  477. has to flush buffers before seeking. None of these considerations apply
  478. to sockets, which don't logically read from and write to the same
  479. mutable store, and are not seekable. Note also that sockets are
  480. unbuffered by default. @xref{Network Sockets and Communication}.
  481. The second case is the more pernicious one. If you write data to a
  482. buffered port, it probably doesn't go out to the mutable store directly.
  483. (This ``probably'' introduces some indeterminism in your program: what
  484. goes to the store, and when, depends on how full the buffer is. It is
  485. something that the user needs to explicitly be aware of.) The data is
  486. written to the store later -- when the buffer fills up due to another
  487. write, or when @code{force-output} is called, or when @code{close-port}
  488. is called, or when the program exits, or even when the garbage collector
  489. runs. The salient point is, @emph{the errors are signalled then too}.
  490. Buffered writes defer error detection (and defer the side effects to the
  491. mutable store), perhaps indefinitely if the port type does not need to
  492. be closed at GC.
  493. One common heuristic that works well for textual ports is to flush
  494. output when a newline (@code{\n}) is written. This @dfn{line buffering}
  495. mode is on by default for TTY ports. Most other ports are @dfn{block
  496. buffered}, meaning that once the output buffer reaches the block size,
  497. which depends on the port and its configuration, the output is flushed
  498. as a block, without regard to what is in the block. Likewise reads are
  499. read in at the block size, though if there are fewer bytes available to
  500. read, the buffer may not be entirely filled.
  501. Note that binary reads or writes that are larger than the buffer size go
  502. directly to the mutable store without passing through the buffers. If
  503. your access pattern involves many big reads or writes, buffering might
  504. not matter so much to you.
  505. To control the buffering behavior of a port, use @code{setvbuf}.
  506. @deffn {Scheme Procedure} setvbuf port mode [size]
  507. @deffnx {C Function} scm_setvbuf (port, mode, size)
  508. @cindex port buffering
  509. Set the buffering mode for @var{port}. @var{mode} can be one of the
  510. following symbols:
  511. @table @code
  512. @item none
  513. non-buffered
  514. @item line
  515. line buffered
  516. @item block
  517. block buffered, using a newly allocated buffer of @var{size} bytes.
  518. If @var{size} is omitted, a default size will be used.
  519. @end table
  520. @end deffn
  521. Another way to set the buffering, for file ports, is to open the file
  522. with @code{0} or @code{l} as part of the mode string, for unbuffered or
  523. line-buffered ports, respectively. @xref{File Ports}, for more.
  524. Any buffered output data will be written out when the port is closed.
  525. To make sure to flush it at specific points in your program, use
  526. @code{force-otput}.
  527. @findex fflush
  528. @deffn {Scheme Procedure} force-output [port]
  529. @deffnx {C Function} scm_force_output (port)
  530. Flush the specified output port, or the current output port if
  531. @var{port} is omitted. The current output buffer contents, if any, are
  532. passed to the underlying port implementation.
  533. The return value is unspecified.
  534. @end deffn
  535. @deffn {Scheme Procedure} flush-all-ports
  536. @deffnx {C Function} scm_flush_all_ports ()
  537. Equivalent to calling @code{force-output} on all open output ports. The
  538. return value is unspecified.
  539. @end deffn
  540. Similarly, sometimes you might want to switch from using Guile's ports
  541. to working directly on file descriptors. In that case, for input ports
  542. use @code{drain-input} to get any buffered input from that port.
  543. @deffn {Scheme Procedure} drain-input port
  544. @deffnx {C Function} scm_drain_input (port)
  545. This procedure clears a port's input buffers, similar
  546. to the way that force-output clears the output buffer. The
  547. contents of the buffers are returned as a single string, e.g.,
  548. @lisp
  549. (define p (open-input-file ...))
  550. (drain-input p) => empty string, nothing buffered yet.
  551. (unread-char (read-char p) p)
  552. (drain-input p) => initial chars from p, up to the buffer size.
  553. @end lisp
  554. @end deffn
  555. All of these considerations are very similar to those of streams in the
  556. C library, although Guile's ports are not built on top of C streams.
  557. Still, it is useful to read what other systems do.
  558. @xref{Streams,,,libc,The GNU C Library Reference Manual}, for more
  559. discussion on C streams.
  560. @node Random Access
  561. @subsection Random Access
  562. @cindex Random access, ports
  563. @cindex Port, random access
  564. @deffn {Scheme Procedure} seek fd_port offset whence
  565. @deffnx {C Function} scm_seek (fd_port, offset, whence)
  566. Sets the current position of @var{fd_port} to the integer
  567. @var{offset}. For a file port, @var{offset} is expressed
  568. as a number of bytes; for other types of ports, such as string
  569. ports, @var{offset} is an abstract representation of the
  570. position within the port's data, not necessarily expressed
  571. as a number of bytes. @var{offset} is interpreted according to
  572. the value of @var{whence}.
  573. One of the following variables should be supplied for
  574. @var{whence}:
  575. @defvar SEEK_SET
  576. Seek from the beginning of the file.
  577. @end defvar
  578. @defvar SEEK_CUR
  579. Seek from the current position.
  580. @end defvar
  581. @defvar SEEK_END
  582. Seek from the end of the file.
  583. @end defvar
  584. If @var{fd_port} is a file descriptor, the underlying system
  585. call is @code{lseek}. @var{port} may be a string port.
  586. The value returned is the new position in @var{fd_port}. This means
  587. that the current position of a port can be obtained using:
  588. @lisp
  589. (seek port 0 SEEK_CUR)
  590. @end lisp
  591. @end deffn
  592. @deffn {Scheme Procedure} ftell fd_port
  593. @deffnx {C Function} scm_ftell (fd_port)
  594. Return an integer representing the current position of
  595. @var{fd_port}, measured from the beginning. Equivalent to:
  596. @lisp
  597. (seek port 0 SEEK_CUR)
  598. @end lisp
  599. @end deffn
  600. @findex truncate
  601. @findex ftruncate
  602. @deffn {Scheme Procedure} truncate-file file [length]
  603. @deffnx {C Function} scm_truncate_file (file, length)
  604. Truncate @var{file} to @var{length} bytes. @var{file} can be a
  605. filename string, a port object, or an integer file descriptor. The
  606. return value is unspecified.
  607. For a port or file descriptor @var{length} can be omitted, in which
  608. case the file is truncated at the current position (per @code{ftell}
  609. above).
  610. On most systems a file can be extended by giving a length greater than
  611. the current size, but this is not mandatory in the POSIX standard.
  612. @end deffn
  613. @node Line/Delimited
  614. @subsection Line Oriented and Delimited Text
  615. @cindex Line input/output
  616. @cindex Port, line input/output
  617. The delimited-I/O module can be accessed with:
  618. @lisp
  619. (use-modules (ice-9 rdelim))
  620. @end lisp
  621. It can be used to read or write lines of text, or read text delimited by
  622. a specified set of characters.
  623. @deffn {Scheme Procedure} read-line [port] [handle-delim]
  624. Return a line of text from @var{port} if specified, otherwise from the
  625. value returned by @code{(current-input-port)}. Under Unix, a line of text
  626. is terminated by the first end-of-line character or by end-of-file.
  627. If @var{handle-delim} is specified, it should be one of the following
  628. symbols:
  629. @table @code
  630. @item trim
  631. Discard the terminating delimiter. This is the default, but it will
  632. be impossible to tell whether the read terminated with a delimiter or
  633. end-of-file.
  634. @item concat
  635. Append the terminating delimiter (if any) to the returned string.
  636. @item peek
  637. Push the terminating delimiter (if any) back on to the port.
  638. @item split
  639. Return a pair containing the string read from the port and the
  640. terminating delimiter or end-of-file object.
  641. @end table
  642. @end deffn
  643. @deffn {Scheme Procedure} read-line! buf [port]
  644. Read a line of text into the supplied string @var{buf} and return the
  645. number of characters added to @var{buf}. If @var{buf} is filled, then
  646. @code{#f} is returned. Read from @var{port} if specified, otherwise
  647. from the value returned by @code{(current-input-port)}.
  648. @end deffn
  649. @deffn {Scheme Procedure} read-delimited delims [port] [handle-delim]
  650. Read text until one of the characters in the string @var{delims} is
  651. found or end-of-file is reached. Read from @var{port} if supplied,
  652. otherwise from the value returned by @code{(current-input-port)}.
  653. @var{handle-delim} takes the same values as described for
  654. @code{read-line}.
  655. @end deffn
  656. @c begin (scm-doc-string "rdelim.scm" "read-delimited!")
  657. @deffn {Scheme Procedure} read-delimited! delims buf [port] [handle-delim] [start] [end]
  658. Read text into the supplied string @var{buf}.
  659. If a delimiter was found, return the number of characters written,
  660. except if @var{handle-delim} is @code{split}, in which case the return
  661. value is a pair, as noted above.
  662. As a special case, if @var{port} was already at end-of-stream, the EOF
  663. object is returned. Also, if no characters were written because the
  664. buffer was full, @code{#f} is returned.
  665. It's something of a wacky interface, to be honest.
  666. @end deffn
  667. @deffn {Scheme Procedure} %read-delimited! delims str gobble [port [start [end]]]
  668. @deffnx {C Function} scm_read_delimited_x (delims, str, gobble, port, start, end)
  669. Read characters from @var{port} into @var{str} until one of the
  670. characters in the @var{delims} string is encountered. If
  671. @var{gobble} is true, discard the delimiter character;
  672. otherwise, leave it in the input stream for the next read. If
  673. @var{port} is not specified, use the value of
  674. @code{(current-input-port)}. If @var{start} or @var{end} are
  675. specified, store data only into the substring of @var{str}
  676. bounded by @var{start} and @var{end} (which default to the
  677. beginning and end of the string, respectively).
  678. Return a pair consisting of the delimiter that terminated the
  679. string and the number of characters read. If reading stopped
  680. at the end of file, the delimiter returned is the
  681. @var{eof-object}; if the string was filled without encountering
  682. a delimiter, this value is @code{#f}.
  683. @end deffn
  684. @deffn {Scheme Procedure} %read-line [port]
  685. @deffnx {C Function} scm_read_line (port)
  686. Read a newline-terminated line from @var{port}, allocating storage as
  687. necessary. The newline terminator (if any) is removed from the string,
  688. and a pair consisting of the line and its delimiter is returned. The
  689. delimiter may be either a newline or the @var{eof-object}; if
  690. @code{%read-line} is called at the end of file, it returns the pair
  691. @code{(#<eof> . #<eof>)}.
  692. @end deffn
  693. @node Default Ports
  694. @subsection Default Ports for Input, Output and Errors
  695. @cindex Default ports
  696. @cindex Port, default
  697. @rnindex current-input-port
  698. @deffn {Scheme Procedure} current-input-port
  699. @deffnx {C Function} scm_current_input_port ()
  700. @cindex standard input
  701. Return the current input port. This is the default port used
  702. by many input procedures.
  703. Initially this is the @dfn{standard input} in Unix and C terminology.
  704. When the standard input is a tty the port is unbuffered, otherwise
  705. it's fully buffered.
  706. Unbuffered input is good if an application runs an interactive
  707. subprocess, since any type-ahead input won't go into Guile's buffer
  708. and be unavailable to the subprocess.
  709. Note that Guile buffering is completely separate from the tty ``line
  710. discipline''. In the usual cooked mode on a tty Guile only sees a
  711. line of input once the user presses @key{Return}.
  712. @end deffn
  713. @rnindex current-output-port
  714. @deffn {Scheme Procedure} current-output-port
  715. @deffnx {C Function} scm_current_output_port ()
  716. @cindex standard output
  717. Return the current output port. This is the default port used
  718. by many output procedures.
  719. Initially this is the @dfn{standard output} in Unix and C terminology.
  720. When the standard output is a tty this port is unbuffered, otherwise
  721. it's fully buffered.
  722. Unbuffered output to a tty is good for ensuring progress output or a
  723. prompt is seen. But an application which always prints whole lines
  724. could change to line buffered, or an application with a lot of output
  725. could go fully buffered and perhaps make explicit @code{force-output}
  726. calls (@pxref{Buffering}) at selected points.
  727. @end deffn
  728. @deffn {Scheme Procedure} current-error-port
  729. @deffnx {C Function} scm_current_error_port ()
  730. @cindex standard error output
  731. Return the port to which errors and warnings should be sent.
  732. Initially this is the @dfn{standard error} in Unix and C terminology.
  733. When the standard error is a tty this port is unbuffered, otherwise
  734. it's fully buffered.
  735. @end deffn
  736. @deffn {Scheme Procedure} set-current-input-port port
  737. @deffnx {Scheme Procedure} set-current-output-port port
  738. @deffnx {Scheme Procedure} set-current-error-port port
  739. @deffnx {C Function} scm_set_current_input_port (port)
  740. @deffnx {C Function} scm_set_current_output_port (port)
  741. @deffnx {C Function} scm_set_current_error_port (port)
  742. Change the ports returned by @code{current-input-port},
  743. @code{current-output-port} and @code{current-error-port}, respectively,
  744. so that they use the supplied @var{port} for input or output.
  745. @end deffn
  746. @deffn {Scheme Procedure} with-input-from-port port thunk
  747. @deffnx {Scheme Procedure} with-output-to-port port thunk
  748. @deffnx {Scheme Procedure} with-error-to-port port thunk
  749. Call @var{thunk} in a dynamic environment in which
  750. @code{current-input-port}, @code{current-output-port} or
  751. @code{current-error-port} is rebound to the given @var{port}.
  752. @end deffn
  753. @deftypefn {C Function} void scm_dynwind_current_input_port (SCM port)
  754. @deftypefnx {C Function} void scm_dynwind_current_output_port (SCM port)
  755. @deftypefnx {C Function} void scm_dynwind_current_error_port (SCM port)
  756. These functions must be used inside a pair of calls to
  757. @code{scm_dynwind_begin} and @code{scm_dynwind_end} (@pxref{Dynamic
  758. Wind}). During the dynwind context, the indicated port is set to
  759. @var{port}.
  760. More precisely, the current port is swapped with a `backup' value
  761. whenever the dynwind context is entered or left. The backup value is
  762. initialized with the @var{port} argument.
  763. @end deftypefn
  764. @node Port Types
  765. @subsection Types of Port
  766. @cindex Types of ports
  767. @cindex Port, types
  768. @menu
  769. * File Ports:: Ports on an operating system file.
  770. * Bytevector Ports:: Ports on a bytevector.
  771. * String Ports:: Ports on a Scheme string.
  772. * Custom Ports:: Ports whose implementation you control.
  773. * Soft Ports:: An older version of custom ports.
  774. * Void Ports:: Ports on nothing at all.
  775. @end menu
  776. @node File Ports
  777. @subsubsection File Ports
  778. @cindex File port
  779. @cindex Port, file
  780. The following procedures are used to open file ports.
  781. See also @ref{Ports and File Descriptors, open}, for an interface
  782. to the Unix @code{open} system call.
  783. All file access uses the ``LFS'' large file support functions when
  784. available, so files bigger than 2 Gbytes (@math{2^31} bytes) can be
  785. read and written on a 32-bit system.
  786. Most systems have limits on how many files can be open, so it's
  787. strongly recommended that file ports be closed explicitly when no
  788. longer required (@pxref{Ports}).
  789. @deffn {Scheme Procedure} open-file filename mode @
  790. [#:guess-encoding=#f] [#:encoding=#f]
  791. @deffnx {C Function} scm_open_file_with_encoding @
  792. (filename, mode, guess_encoding, encoding)
  793. @deffnx {C Function} scm_open_file (filename, mode)
  794. Open the file whose name is @var{filename}, and return a port
  795. representing that file. The attributes of the port are
  796. determined by the @var{mode} string. The way in which this is
  797. interpreted is similar to C stdio. The first character must be
  798. one of the following:
  799. @table @samp
  800. @item r
  801. Open an existing file for input.
  802. @item w
  803. Open a file for output, creating it if it doesn't already exist
  804. or removing its contents if it does.
  805. @item a
  806. Open a file for output, creating it if it doesn't already
  807. exist. All writes to the port will go to the end of the file.
  808. The "append mode" can be turned off while the port is in use
  809. @pxref{Ports and File Descriptors, fcntl}
  810. @end table
  811. The following additional characters can be appended:
  812. @table @samp
  813. @item +
  814. Open the port for both input and output. E.g., @code{r+}: open
  815. an existing file for both input and output.
  816. @item 0
  817. Create an "unbuffered" port. In this case input and output
  818. operations are passed directly to the underlying port
  819. implementation without additional buffering. This is likely to
  820. slow down I/O operations. The buffering mode can be changed
  821. while a port is in use (@pxref{Buffering}).
  822. @item l
  823. Add line-buffering to the port. The port output buffer will be
  824. automatically flushed whenever a newline character is written.
  825. @item b
  826. Use binary mode, ensuring that each byte in the file will be read as one
  827. Scheme character.
  828. To provide this property, the file will be opened with the 8-bit
  829. character encoding "ISO-8859-1", ignoring the default port encoding.
  830. @xref{Ports}, for more information on port encodings.
  831. Note that while it is possible to read and write binary data as
  832. characters or strings, it is usually better to treat bytes as octets,
  833. and byte sequences as bytevectors. @xref{Binary I/O}, for more.
  834. This option had another historical meaning, for DOS compatibility: in
  835. the default (textual) mode, DOS reads a CR-LF sequence as one LF byte.
  836. The @code{b} flag prevents this from happening, adding @code{O_BINARY}
  837. to the underlying @code{open} call. Still, the flag is generally useful
  838. because of its port encoding ramifications.
  839. @end table
  840. Unless binary mode is requested, the character encoding of the new port
  841. is determined as follows: First, if @var{guess-encoding} is true, the
  842. @code{file-encoding} procedure is used to guess the encoding of the file
  843. (@pxref{Character Encoding of Source Files}). If @var{guess-encoding}
  844. is false or if @code{file-encoding} fails, @var{encoding} is used unless
  845. it is also false. As a last resort, the default port encoding is used.
  846. @xref{Ports}, for more information on port encodings. It is an error to
  847. pass a non-false @var{guess-encoding} or @var{encoding} if binary mode
  848. is requested.
  849. If a file cannot be opened with the access requested, @code{open-file}
  850. throws an exception.
  851. @end deffn
  852. @rnindex open-input-file
  853. @deffn {Scheme Procedure} open-input-file filename @
  854. [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]
  855. Open @var{filename} for input. If @var{binary} is true, open the port
  856. in binary mode, otherwise use text mode. @var{encoding} and
  857. @var{guess-encoding} determine the character encoding as described above
  858. for @code{open-file}. Equivalent to
  859. @lisp
  860. (open-file @var{filename}
  861. (if @var{binary} "rb" "r")
  862. #:guess-encoding @var{guess-encoding}
  863. #:encoding @var{encoding})
  864. @end lisp
  865. @end deffn
  866. @rnindex open-output-file
  867. @deffn {Scheme Procedure} open-output-file filename @
  868. [#:encoding=#f] [#:binary=#f]
  869. Open @var{filename} for output. If @var{binary} is true, open the port
  870. in binary mode, otherwise use text mode. @var{encoding} specifies the
  871. character encoding as described above for @code{open-file}. Equivalent
  872. to
  873. @lisp
  874. (open-file @var{filename}
  875. (if @var{binary} "wb" "w")
  876. #:encoding @var{encoding})
  877. @end lisp
  878. @end deffn
  879. @deffn {Scheme Procedure} call-with-input-file filename proc @
  880. [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]
  881. @deffnx {Scheme Procedure} call-with-output-file filename proc @
  882. [#:encoding=#f] [#:binary=#f]
  883. @rnindex call-with-input-file
  884. @rnindex call-with-output-file
  885. Open @var{filename} for input or output, and call @code{(@var{proc}
  886. port)} with the resulting port. Return the value returned by
  887. @var{proc}. @var{filename} is opened as per @code{open-input-file} or
  888. @code{open-output-file} respectively, and an error is signaled if it
  889. cannot be opened.
  890. When @var{proc} returns, the port is closed. If @var{proc} does not
  891. return (e.g.@: if it throws an error), then the port might not be
  892. closed automatically, though it will be garbage collected in the usual
  893. way if not otherwise referenced.
  894. @end deffn
  895. @deffn {Scheme Procedure} with-input-from-file filename thunk @
  896. [#:guess-encoding=#f] [#:encoding=#f] [#:binary=#f]
  897. @deffnx {Scheme Procedure} with-output-to-file filename thunk @
  898. [#:encoding=#f] [#:binary=#f]
  899. @deffnx {Scheme Procedure} with-error-to-file filename thunk @
  900. [#:encoding=#f] [#:binary=#f]
  901. @rnindex with-input-from-file
  902. @rnindex with-output-to-file
  903. Open @var{filename} and call @code{(@var{thunk})} with the new port
  904. setup as respectively the @code{current-input-port},
  905. @code{current-output-port}, or @code{current-error-port}. Return the
  906. value returned by @var{thunk}. @var{filename} is opened as per
  907. @code{open-input-file} or @code{open-output-file} respectively, and an
  908. error is signaled if it cannot be opened.
  909. When @var{thunk} returns, the port is closed and the previous setting
  910. of the respective current port is restored.
  911. The current port setting is managed with @code{dynamic-wind}, so the
  912. previous value is restored no matter how @var{thunk} exits (eg.@: an
  913. exception), and if @var{thunk} is re-entered (via a captured
  914. continuation) then it's set again to the @var{filename} port.
  915. The port is closed when @var{thunk} returns normally, but not when
  916. exited via an exception or new continuation. This ensures it's still
  917. ready for use if @var{thunk} is re-entered by a captured continuation.
  918. Of course the port is always garbage collected and closed in the usual
  919. way when no longer referenced anywhere.
  920. @end deffn
  921. @deffn {Scheme Procedure} port-mode port
  922. @deffnx {C Function} scm_port_mode (port)
  923. Return the port modes associated with the open port @var{port}.
  924. These will not necessarily be identical to the modes used when
  925. the port was opened, since modes such as "append" which are
  926. used only during port creation are not retained.
  927. @end deffn
  928. @deffn {Scheme Procedure} port-filename port
  929. @deffnx {C Function} scm_port_filename (port)
  930. Return the filename associated with @var{port}, or @code{#f} if no
  931. filename is associated with the port.
  932. @var{port} must be open; @code{port-filename} cannot be used once the
  933. port is closed.
  934. @end deffn
  935. @deffn {Scheme Procedure} set-port-filename! port filename
  936. @deffnx {C Function} scm_set_port_filename_x (port, filename)
  937. Change the filename associated with @var{port}, using the current input
  938. port if none is specified. Note that this does not change the port's
  939. source of data, but only the value that is returned by
  940. @code{port-filename} and reported in diagnostic output.
  941. @end deffn
  942. @deffn {Scheme Procedure} file-port? obj
  943. @deffnx {C Function} scm_file_port_p (obj)
  944. Determine whether @var{obj} is a port that is related to a file.
  945. @end deffn
  946. @node Bytevector Ports
  947. @subsubsection Bytevector Ports
  948. @deffn {Scheme Procedure} open-bytevector-input-port bv [transcoder]
  949. @deffnx {C Function} scm_open_bytevector_input_port (bv, transcoder)
  950. Return an input port whose contents are drawn from bytevector @var{bv}
  951. (@pxref{Bytevectors}).
  952. @c FIXME: Update description when implemented.
  953. The @var{transcoder} argument is currently not supported.
  954. @end deffn
  955. @deffn {Scheme Procedure} open-bytevector-output-port [transcoder]
  956. @deffnx {C Function} scm_open_bytevector_output_port (transcoder)
  957. Return two values: a binary output port and a procedure. The latter
  958. should be called with zero arguments to obtain a bytevector containing
  959. the data accumulated by the port, as illustrated below.
  960. @lisp
  961. (call-with-values
  962. (lambda ()
  963. (open-bytevector-output-port))
  964. (lambda (port get-bytevector)
  965. (display "hello" port)
  966. (get-bytevector)))
  967. @result{} #vu8(104 101 108 108 111)
  968. @end lisp
  969. @c FIXME: Update description when implemented.
  970. The @var{transcoder} argument is currently not supported.
  971. @end deffn
  972. @node String Ports
  973. @subsubsection String Ports
  974. @cindex String port
  975. @cindex Port, string
  976. @deffn {Scheme Procedure} call-with-output-string proc
  977. @deffnx {C Function} scm_call_with_output_string (proc)
  978. Calls the one-argument procedure @var{proc} with a newly created output
  979. port. When the function returns, the string composed of the characters
  980. written into the port is returned. @var{proc} should not close the port.
  981. @end deffn
  982. @deffn {Scheme Procedure} call-with-input-string string proc
  983. @deffnx {C Function} scm_call_with_input_string (string, proc)
  984. Calls the one-argument procedure @var{proc} with a newly
  985. created input port from which @var{string}'s contents may be
  986. read. The value yielded by the @var{proc} is returned.
  987. @end deffn
  988. @deffn {Scheme Procedure} with-output-to-string thunk
  989. Calls the zero-argument procedure @var{thunk} with the current output
  990. port set temporarily to a new string port. It returns a string
  991. composed of the characters written to the current output.
  992. @end deffn
  993. @deffn {Scheme Procedure} with-input-from-string string thunk
  994. Calls the zero-argument procedure @var{thunk} with the current input
  995. port set temporarily to a string port opened on the specified
  996. @var{string}. The value yielded by @var{thunk} is returned.
  997. @end deffn
  998. @deffn {Scheme Procedure} open-input-string str
  999. @deffnx {C Function} scm_open_input_string (str)
  1000. Take a string and return an input port that delivers characters
  1001. from the string. The port can be closed by
  1002. @code{close-input-port}, though its storage will be reclaimed
  1003. by the garbage collector if it becomes inaccessible.
  1004. @end deffn
  1005. @deffn {Scheme Procedure} open-output-string
  1006. @deffnx {C Function} scm_open_output_string ()
  1007. Return an output port that will accumulate characters for
  1008. retrieval by @code{get-output-string}. The port can be closed
  1009. by the procedure @code{close-output-port}, though its storage
  1010. will be reclaimed by the garbage collector if it becomes
  1011. inaccessible.
  1012. @end deffn
  1013. @deffn {Scheme Procedure} get-output-string port
  1014. @deffnx {C Function} scm_get_output_string (port)
  1015. Given an output port created by @code{open-output-string},
  1016. return a string consisting of the characters that have been
  1017. output to the port so far.
  1018. @code{get-output-string} must be used before closing @var{port}, once
  1019. closed the string cannot be obtained.
  1020. @end deffn
  1021. With string ports, the port-encoding is treated differently than other
  1022. types of ports. When string ports are created, they do not inherit a
  1023. character encoding from the current locale. They are given a
  1024. default locale that allows them to handle all valid string characters.
  1025. Typically one should not modify a string port's character encoding
  1026. away from its default. @xref{Encoding}.
  1027. @node Custom Ports
  1028. @subsubsection Custom Ports
  1029. Custom ports allow the user to provide input and handle output via
  1030. user-supplied procedures. Guile currently only provides custom binary
  1031. ports, not textual ports; for custom textual ports, @xref{Soft Ports}.
  1032. We should add the R6RS custom textual port interfaces though.
  1033. Contributions are appreciated.
  1034. @cindex custom binary input ports
  1035. @deffn {Scheme Procedure} make-custom-binary-input-port id read! get-position set-position! close
  1036. Return a new custom binary input port@footnote{This is similar in spirit
  1037. to Guile's @dfn{soft ports} (@pxref{Soft Ports}).} named @var{id} (a
  1038. string) whose input is drained by invoking @var{read!} and passing it a
  1039. bytevector, an index where bytes should be written, and the number of
  1040. bytes to read. The @code{read!} procedure must return an integer
  1041. indicating the number of bytes read, or @code{0} to indicate the
  1042. end-of-file.
  1043. Optionally, if @var{get-position} is not @code{#f}, it must be a thunk
  1044. that will be called when @code{port-position} is invoked on the custom
  1045. binary port and should return an integer indicating the position within
  1046. the underlying data stream; if @var{get-position} was not supplied, the
  1047. returned port does not support @code{port-position}.
  1048. Likewise, if @var{set-position!} is not @code{#f}, it should be a
  1049. one-argument procedure. When @code{set-port-position!} is invoked on the
  1050. custom binary input port, @var{set-position!} is passed an integer
  1051. indicating the position of the next byte is to read.
  1052. Finally, if @var{close} is not @code{#f}, it must be a thunk. It is
  1053. invoked when the custom binary input port is closed.
  1054. The returned port is fully buffered by default, but its buffering mode
  1055. can be changed using @code{setvbuf} (@pxref{Buffering}).
  1056. Using a custom binary input port, the @code{open-bytevector-input-port}
  1057. procedure (@pxref{Bytevector Ports}) could be implemented as follows:
  1058. @lisp
  1059. (define (open-bytevector-input-port source)
  1060. (define position 0)
  1061. (define length (bytevector-length source))
  1062. (define (read! bv start count)
  1063. (let ((count (min count (- length position))))
  1064. (bytevector-copy! source position
  1065. bv start count)
  1066. (set! position (+ position count))
  1067. count))
  1068. (define (get-position) position)
  1069. (define (set-position! new-position)
  1070. (set! position new-position))
  1071. (make-custom-binary-input-port "the port" read!
  1072. get-position set-position!
  1073. #f))
  1074. (read (open-bytevector-input-port (string->utf8 "hello")))
  1075. @result{} hello
  1076. @end lisp
  1077. @end deffn
  1078. @cindex custom binary output ports
  1079. @deffn {Scheme Procedure} make-custom-binary-output-port id write! get-position set-position! close
  1080. Return a new custom binary output port named @var{id} (a string) whose
  1081. output is sunk by invoking @var{write!} and passing it a bytevector, an
  1082. index where bytes should be read from this bytevector, and the number of
  1083. bytes to be ``written''. The @code{write!} procedure must return an
  1084. integer indicating the number of bytes actually written; when it is
  1085. passed @code{0} as the number of bytes to write, it should behave as
  1086. though an end-of-file was sent to the byte sink.
  1087. The other arguments are as for @code{make-custom-binary-input-port}.
  1088. @end deffn
  1089. @cindex custom binary input/output ports
  1090. @deffn {Scheme Procedure} make-custom-binary-input/output-port id read! write! get-position set-position! close
  1091. Return a new custom binary input/output port named @var{id} (a string).
  1092. The various arguments are the same as for The other arguments are as for
  1093. @code{make-custom-binary-input-port} and
  1094. @code{make-custom-binary-output-port}. If buffering is enabled on the
  1095. port, as is the case by default, input will be buffered in both
  1096. directions; @xref{Buffering}. If the @var{set-position!} function is
  1097. provided and not @code{#f}, then the port will also be marked as
  1098. random-access, causing the buffer to be flushed between reads and
  1099. writes.
  1100. @end deffn
  1101. @node Soft Ports
  1102. @subsubsection Soft Ports
  1103. @cindex Soft port
  1104. @cindex Port, soft
  1105. A @dfn{soft port} is a port based on a vector of procedures capable of
  1106. accepting or delivering characters. It allows emulation of I/O ports.
  1107. @deffn {Scheme Procedure} make-soft-port pv modes
  1108. Return a port capable of receiving or delivering characters as
  1109. specified by the @var{modes} string (@pxref{File Ports,
  1110. open-file}). @var{pv} must be a vector of length 5 or 6. Its
  1111. components are as follows:
  1112. @enumerate 0
  1113. @item
  1114. procedure accepting one character for output
  1115. @item
  1116. procedure accepting a string for output
  1117. @item
  1118. thunk for flushing output
  1119. @item
  1120. thunk for getting one character
  1121. @item
  1122. thunk for closing port (not by garbage collection)
  1123. @item
  1124. (if present and not @code{#f}) thunk for computing the number of
  1125. characters that can be read from the port without blocking.
  1126. @end enumerate
  1127. For an output-only port only elements 0, 1, 2, and 4 need be
  1128. procedures. For an input-only port only elements 3 and 4 need
  1129. be procedures. Thunks 2 and 4 can instead be @code{#f} if
  1130. there is no useful operation for them to perform.
  1131. If thunk 3 returns @code{#f} or an @code{eof-object}
  1132. (@pxref{Input, eof-object?, ,r5rs, The Revised^5 Report on
  1133. Scheme}) it indicates that the port has reached end-of-file.
  1134. For example:
  1135. @lisp
  1136. (define stdout (current-output-port))
  1137. (define p (make-soft-port
  1138. (vector
  1139. (lambda (c) (write c stdout))
  1140. (lambda (s) (display s stdout))
  1141. (lambda () (display "." stdout))
  1142. (lambda () (char-upcase (read-char)))
  1143. (lambda () (display "@@" stdout)))
  1144. "rw"))
  1145. (write p p) @result{} #<input-output: soft 8081e20>
  1146. @end lisp
  1147. @end deffn
  1148. @node Void Ports
  1149. @subsubsection Void Ports
  1150. @cindex Void port
  1151. @cindex Port, void
  1152. This kind of port causes any data to be discarded when written to, and
  1153. always returns the end-of-file object when read from.
  1154. @deffn {Scheme Procedure} %make-void-port mode
  1155. @deffnx {C Function} scm_sys_make_void_port (mode)
  1156. Create and return a new void port. A void port acts like
  1157. @file{/dev/null}. The @var{mode} argument
  1158. specifies the input/output modes for this port: see the
  1159. documentation for @code{open-file} in @ref{File Ports}.
  1160. @end deffn
  1161. @node Venerable Port Interfaces
  1162. @subsection Venerable Port Interfaces
  1163. Over the 25 years or so that Guile has been around, its port system has
  1164. evolved, adding many useful features. At the same time there have been
  1165. four major Scheme standards released in those 25 years, which also
  1166. evolve the common Scheme understanding of what a port interface should
  1167. be. Alas, it would be too much to ask for all of these evolutionary
  1168. branches to be consistent. Some of Guile's original interfaces don't
  1169. mesh with the later Scheme standards, and yet Guile can't just drop old
  1170. interfaces. Sadly as well, the R6RS and R7RS standards both part from a
  1171. base of R5RS, but end up in different and somewhat incompatible designs.
  1172. Guile's approach is to pick a set of port primitives that make sense
  1173. together. We document that set of primitives, design our internal
  1174. interfaces around them, and recommend them to users. As the R6RS I/O
  1175. system is the most capable standard that Scheme has yet produced in this
  1176. domain, we mostly recommend that; @code{(ice-9 binary-ports)} and
  1177. @code{(ice-9 textual-ports)} are wholly modelled on @code{(rnrs io
  1178. ports)}. Guile does not wholly copy R6RS, however; @xref{R6RS
  1179. Incompatibilities}.
  1180. At the same time, we have many venerable port interfaces, lore handed
  1181. down to us from our hacker ancestors. Most of these interfaces even
  1182. predate the expectation that Scheme should have modules, so they are
  1183. present in the default environment. In Guile we support them as well
  1184. and we have no plans to remove them, but again we don't recommend them
  1185. for new users.
  1186. @rnindex char-ready?
  1187. @deffn {Scheme Procedure} char-ready? [port]
  1188. Return @code{#t} if a character is ready on input @var{port}
  1189. and return @code{#f} otherwise. If @code{char-ready?} returns
  1190. @code{#t} then the next @code{read-char} operation on
  1191. @var{port} is guaranteed not to hang. If @var{port} is a file
  1192. port at end of file then @code{char-ready?} returns @code{#t}.
  1193. @code{char-ready?} exists to make it possible for a
  1194. program to accept characters from interactive ports without
  1195. getting stuck waiting for input. Any input editors associated
  1196. with such ports must make sure that characters whose existence
  1197. has been asserted by @code{char-ready?} cannot be rubbed out.
  1198. If @code{char-ready?} were to return @code{#f} at end of file,
  1199. a port at end of file would be indistinguishable from an
  1200. interactive port that has no ready characters.
  1201. Note that @code{char-ready?} only works reliably for terminals and
  1202. sockets with one-byte encodings. Under the hood it will return
  1203. @code{#t} if the port has any input buffered, or if the file descriptor
  1204. that backs the port polls as readable, indicating that Guile can fetch
  1205. more bytes from the kernel. However being able to fetch one byte
  1206. doesn't mean that a full character is available; @xref{Encoding}. Also,
  1207. on many systems it's possible for a file descriptor to poll as readable,
  1208. but then block when it comes time to read bytes. Note also that on
  1209. Linux kernels, all file ports backed by files always poll as readable.
  1210. For non-file ports, this procedure always returns @code{#t}, except for
  1211. soft ports, which have a @code{char-ready?} handler. @xref{Soft Ports}.
  1212. In short, this is a legacy procedure whose semantics are hard to
  1213. provide. However it is a useful check to see if any input is buffered.
  1214. @xref{Non-Blocking I/O}.
  1215. @end deffn
  1216. @rnindex read-char
  1217. @deffn {Scheme Procedure} read-char [port]
  1218. The same as @code{get-char}, except that @var{port} defaults to the
  1219. current input port. @xref{Textual I/O}.
  1220. @end deffn
  1221. @rnindex peek-char
  1222. @deffn {Scheme Procedure} peek-char [port]
  1223. The same as @code{lookahead-char}, except that @var{port} defaults to
  1224. the current input port. @xref{Textual I/O}.
  1225. @end deffn
  1226. @deffn {Scheme Procedure} unread-char cobj [port]
  1227. The same as @code{unget-char}, except that @var{port} defaults to the
  1228. current input port, and the arguments are swapped. @xref{Textual I/O}.
  1229. @end deffn
  1230. @deffn {Scheme Procedure} unread-string str port
  1231. @deffnx {C Function} scm_unread_string (str, port)
  1232. The same as @code{unget-string}, except that @var{port} defaults to the
  1233. current input port, and the arguments are swapped. @xref{Textual I/O}.
  1234. @end deffn
  1235. @rnindex newline
  1236. @deffn {Scheme Procedure} newline [port]
  1237. Send a newline to @var{port}. If @var{port} is omitted, send to the
  1238. current output port. Equivalent to @code{(put-char port #\newline)}.
  1239. @end deffn
  1240. @rnindex write-char
  1241. @deffn {Scheme Procedure} write-char chr [port]
  1242. The same as @code{put-char}, except that @var{port} defaults to the
  1243. current input port, and the arguments are swapped. @xref{Textual I/O}.
  1244. @end deffn
  1245. @node Using Ports from C
  1246. @subsection Using Ports from C
  1247. Guile's C interfaces provides some niceties for sending and receiving
  1248. bytes and characters in a way that works better with C.
  1249. @deftypefn {C Function} size_t scm_c_read (SCM port, void *buffer, size_t size)
  1250. Read up to @var{size} bytes from @var{port} and store them in
  1251. @var{buffer}. The return value is the number of bytes actually read,
  1252. which can be less than @var{size} if end-of-file has been reached.
  1253. Note that as this is a binary input procedure, this function does not
  1254. update @code{port-line} and @code{port-column} (@pxref{Textual I/O}).
  1255. @end deftypefn
  1256. @deftypefn {C Function} void scm_c_write (SCM port, const void *buffer, size_t size)
  1257. Write @var{size} bytes at @var{buffer} to @var{port}.
  1258. Note that as this is a binary output procedure, this function does not
  1259. update @code{port-line} and @code{port-column} (@pxref{Textual I/O}).
  1260. @end deftypefn
  1261. @deftypefn {C Function} size_t scm_c_read_bytes (SCM port, SCM bv, size_t start, size_t count)
  1262. @deftypefnx {C Function} void scm_c_write_bytes (SCM port, SCM bv, size_t start, size_t count)
  1263. Like @code{scm_c_read} and @code{scm_c_write}, but reading into or
  1264. writing from the bytevector @var{bv}. @var{count} indicates the byte
  1265. index at which to start in the bytevector, and the read or write will
  1266. continue for @var{count} bytes.
  1267. @end deftypefn
  1268. @deftypefn {C Function} void scm_unget_bytes (const unsigned char *buf, size_t len, SCM port)
  1269. @deftypefnx {C Function} void scm_unget_byte (int c, SCM port)
  1270. @deftypefnx {C Function} void scm_ungetc (scm_t_wchar c, SCM port)
  1271. Like @code{unget-bytevector}, @code{unget-byte}, and @code{unget-char},
  1272. respectively. @xref{Textual I/O}.
  1273. @end deftypefn
  1274. @deftypefn {C Function} void scm_c_put_latin1_chars (SCM port, const scm_t_uint8 *buf, size_t len)
  1275. @deftypefnx {C Function} void scm_c_put_utf32_chars (SCM port, const scm_t_uint32 *buf, size_t len);
  1276. Write a string to @var{port}. In the first case, the
  1277. @code{scm_t_uint8*} buffer is a string in the latin-1 encoding. In the
  1278. second, the @code{scm_t_uint32*} buffer is a string in the UTF-32
  1279. encoding. These routines will update the port's line and column.
  1280. @end deftypefn
  1281. @node I/O Extensions
  1282. @subsection Implementing New Port Types in C
  1283. This section describes how to implement a new port type in C. Although
  1284. ports support many operations, as a data structure they present an
  1285. opaque interface to the user. To the port implementor, you have two
  1286. pieces of information to work with: the port type, and the port's
  1287. ``stream''. The port type is an opaque pointer allocated when defining
  1288. your port type. It is your key into the port API, and it helps you
  1289. identify which ports are actually yours. The ``stream'' is a pointer
  1290. you control, and which you set when you create a port. Get a stream
  1291. from a port using the @code{SCM_STREAM} macro. Note that your port
  1292. methods are only ever called with ports of your type.
  1293. A port type is created by calling @code{scm_make_port_type}. Once you
  1294. have your port type, you can create ports with @code{scm_c_make_port},
  1295. or @code{scm_c_make_port_with_encoding}.
  1296. @deftypefun scm_t_port_type* scm_make_port_type (char *name, size_t (*read) (SCM port, SCM dst, size_t start, size_t count), size_t (*write) (SCM port, SCM src, size_t start, size_t count))
  1297. Define a new port type. The @var{name}, @var{read} and @var{write}
  1298. parameters are initial values for those port type fields, as described
  1299. below. The other fields are initialized with default values and can be
  1300. changed later.
  1301. @end deftypefun
  1302. @deftypefun SCM scm_c_make_port_with_encoding (scm_t_port_type *type, unsigned long mode_bits, SCM encoding, SCM conversion_strategy, scm_t_bits stream)
  1303. @deftypefunx SCM scm_c_make_port (scm_t_port_type *type, unsigned long mode_bits, scm_t_bits stream)
  1304. Make a port with the given @var{type}. The @var{stream} indicates the
  1305. private data associated with the port, which your port implementation
  1306. may later retrieve with @code{SCM_STREAM}. The mode bits should include
  1307. one or more of the flags @code{SCM_RDNG} or @code{SCM_WRTNG}, indicating
  1308. that the port is an input and/or an output port, respectively. The mode
  1309. bits may also include @code{SCM_BUF0} or @code{SCM_BUFLINE}, indicating
  1310. that the port should be unbuffered or line-buffered, respectively. The
  1311. default is that the port will be block-buffered. @xref{Buffering}.
  1312. As you would imagine, @var{encoding} and @var{conversion_strategy}
  1313. specify the port's initial textual encoding and conversion strategy.
  1314. Both are symbols. @code{scm_c_make_port} is the same as
  1315. @code{scm_c_make_port_with_encoding}, except it uses the default port
  1316. encoding and conversion strategy.
  1317. @end deftypefun
  1318. The port type has a number of associate procedures and properties which
  1319. collectively implement the port's behavior. Creating a new port type
  1320. mostly involves writing these procedures.
  1321. @table @code
  1322. @item name
  1323. A pointer to a NUL terminated string: the name of the port type. This
  1324. property is initialized via the first argument to
  1325. @code{scm_make_port_type}.
  1326. @item read
  1327. A port's @code{read} implementation fills read buffers. It should copy
  1328. bytes to the supplied bytevector @code{dst}, starting at offset
  1329. @code{start} and continuing for @code{count} bytes, returning the number
  1330. of bytes read.
  1331. @item write
  1332. A port's @code{write} implementation flushes write buffers to the
  1333. mutable store. A port's @code{read} implementation fills read buffers.
  1334. It should write out bytes from the supplied bytevector @code{src},
  1335. starting at offset @code{start} and continuing for @code{count} bytes,
  1336. and return the number of bytes that were written.
  1337. @item read_wait_fd
  1338. @itemx write_wait_fd
  1339. If a port's @code{read} or @code{write} function returns @code{(size_t)
  1340. -1}, that indicates that reading or writing would block. In that case
  1341. to preserve the illusion of a blocking read or write operation, Guile's
  1342. C port run-time will @code{poll} on the file descriptor returned by
  1343. either the port's @code{read_wait_fd} or @code{write_wait_fd} function.
  1344. Set using
  1345. @deftypefun void scm_set_port_read_wait_fd (scm_t_port_type *type, int (*wait_fd) (SCM port))
  1346. @deftypefunx void scm_set_port_write_wait_fd (scm_t_port_type *type, int (*wait_fd) (SCM port))
  1347. @end deftypefun
  1348. Only a port type which implements the @code{read_wait_fd} or
  1349. @code{write_wait_fd} port methods can usefully return @code{(size_t) -1}
  1350. from a read or write function. @xref{Non-Blocking I/O}, for more on
  1351. non-blocking I/O in Guile.
  1352. @item print
  1353. Called when @code{write} is called on the port, to print a port
  1354. description. For example, for a file port it may produce something
  1355. like: @code{#<input: /etc/passwd 3>}. Set using
  1356. @deftypefun void scm_set_port_print (scm_t_port_type *type, int (*print) (SCM port, SCM dest_port, scm_print_state *pstate))
  1357. The first argument @var{port} is the port being printed, the second
  1358. argument @var{dest_port} is where its description should go.
  1359. @end deftypefun
  1360. @item close
  1361. Called when the port is closed. It should free any resources used by
  1362. the port. Set using
  1363. @deftypefun void scm_set_port_close (scm_t_port_type *type, void (*close) (SCM port))
  1364. @end deftypefun
  1365. By default, ports that are garbage collected just go away without
  1366. closing. If your port type needs to release some external resource like
  1367. a file descriptor, or needs to make sure that its internal buffers are
  1368. flushed even if the port is collected while it was open, then mark the
  1369. port type as needing a close on GC.
  1370. @deftypefun void scm_set_port_needs_close_on_gc (scm_t_port_type *type, int needs_close_p)
  1371. @end deftypefun
  1372. @item seek
  1373. Set the current position of the port. Guile will flush read and/or
  1374. write buffers before seeking, as appropriate.
  1375. @deftypefun void scm_set_port_seek (scm_t_port_type *type, scm_t_off (*seek) (SCM port, scm_t_off offset, int whence))
  1376. @end deftypefun
  1377. @item truncate
  1378. Truncate the port data to be specified length. Guile will flush buffers
  1379. before hand, as appropriate. Set using
  1380. @deftypefun void scm_set_port_truncate (scm_t_port_type *type, void (*truncate) (SCM port, scm_t_off length))
  1381. @end deftypefun
  1382. @item random_access_p
  1383. Determine whether this port is a random-access port.
  1384. @cindex random access
  1385. Seeking on a random-access port with buffered input, or switching to
  1386. writing after reading, will cause the buffered input to be discarded and
  1387. Guile will seek the port back the buffered number of bytes. Likewise
  1388. seeking on a random-access port with buffered output, or switching to
  1389. reading after writing, will flush pending bytes with a call to the
  1390. @code{write} procedure. @xref{Buffering}.
  1391. Indicate to Guile that your port needs this behavior by returning a
  1392. nonzero value from your @code{random_access_p} function. The default
  1393. implementation of this function returns nonzero if the port type
  1394. supplies a seek implementation.
  1395. @deftypefun void scm_set_port_random_access_p (scm_t_port_type *type, int (*random_access_p) (SCM port));
  1396. @end deftypefun
  1397. @item get_natural_buffer_sizes
  1398. Guile will internally attach buffers to ports. An input port always has
  1399. a read buffer and an output port always has a write buffer.
  1400. @xref{Buffering}. A port buffer consists of a bytevector, along with
  1401. some cursors into that bytevector denoting where to get and put data.
  1402. Port implementations generally don't have to be concerned with
  1403. buffering: a port type's @code{read} or @code{write} function will
  1404. receive the buffer's bytevector as an argument, along with an offset and
  1405. a length into that bytevector, and should then either fill or empty that
  1406. bytevector. However in some cases, port implementations may be able to
  1407. provide an appropriate default buffer size to Guile.
  1408. @deftypefun void scm_set_port_get_natural_buffer_sizes @
  1409. (scm_t_port_type *type, void (*get_natural_buffer_sizes) (SCM, size_t *read_buf_size, size_t *write_buf_size))
  1410. Fill in @var{read_buf_size} and @var{write_buf_size} with an appropriate buffer size for this port, if one is known.
  1411. @end deftypefun
  1412. File ports implement a @code{get_natural_buffer_sizes} to let the
  1413. operating system inform Guile about the appropriate buffer sizes for the
  1414. particular file opened by the port.
  1415. @end table
  1416. Note that calls to all of these methods can proceed in parallel and
  1417. concurrently and from any thread up until the point that the port is
  1418. closed. The call to @code{close} will happen when no other method is
  1419. running, and no method will be called after the @code{close} method is
  1420. called. If your port implementation needs mutual exclusion to prevent
  1421. concurrency, it is responsible for locking appropriately.
  1422. @node Non-Blocking I/O
  1423. @subsection Non-Blocking I/O
  1424. Most ports in Guile are @dfn{blocking}: when you try to read a character
  1425. from a port, Guile will block on the read until a character is ready, or
  1426. end-of-stream is detected. Likewise whenever Guile goes to write
  1427. (possibly buffered) data to an output port, Guile will block until all
  1428. the data is written.
  1429. Interacting with ports in blocking mode is very convenient: you can
  1430. write straightforward, sequential algorithms whose code flow reflects
  1431. the flow of data. However, blocking I/O has two main limitations.
  1432. The first is that it's easy to get into a situation where code is
  1433. waiting on data. Time spent waiting on data when code could be doing
  1434. something else is wasteful and prevents your program from reaching its
  1435. peak throughput. If you implement a web server that sequentially
  1436. handles requests from clients, it's very easy for the server to end up
  1437. waiting on a client to finish its HTTP request, or waiting on it to
  1438. consume the response. The end result is that you are able to serve
  1439. fewer requests per second than you'd like to serve.
  1440. The second limitation is related: a blocking parser over user-controlled
  1441. input is a denial-of-service vulnerability. Indeed the so-called ``slow
  1442. loris'' attack of the early 2010s was just that: an attack on common web
  1443. servers that drip-fed HTTP requests, one character at a time. All it
  1444. took was a handful of slow loris connections to occupy an entire web
  1445. server.
  1446. In Guile we would like to preserve the ability to write straightforward
  1447. blocking networking processes of all kinds, but under the hood to allow
  1448. those processes to suspend their requests if they would block.
  1449. To do this, the first piece is to allow Guile ports to declare
  1450. themselves as being nonblocking. This is currently supported only for
  1451. file ports, which also includes sockets, terminals, or any other port
  1452. that is backed by a file descriptor. To do that, we use an arcane UNIX
  1453. incantation:
  1454. @example
  1455. (let ((flags (fcntl socket F_GETFL)))
  1456. (fcntl socket F_SETFL (logior O_NONBLOCK flags)))
  1457. @end example
  1458. Now the file descriptor is open in non-blocking mode. If Guile tries to
  1459. read or write from this file and the read or write returns a result
  1460. indicating that more data can only be had by doing a blocking read or
  1461. write, Guile will block by polling on the socket's @code{read-wait-fd}
  1462. or @code{write-wait-fd}, to preserve the illusion of a blocking read or
  1463. write. @xref{I/O Extensions} for more on those internal interfaces.
  1464. So far we have just reproduced the status quo: the file descriptor is
  1465. non-blocking, but the operations on the port do block. To go farther,
  1466. it would be nice if we could suspend the ``thread'' using delimited
  1467. continuations, and only resume the thread once the file descriptor is
  1468. readable or writable. (@xref{Prompts}).
  1469. But here we run into a difficulty. The ports code is implemented in C,
  1470. which means that although we can suspend the computation to some outer
  1471. prompt, we can't resume it because Guile can't resume delimited
  1472. continuations that capture the C stack.
  1473. To overcome this difficulty we have created a compatible but entirely
  1474. parallel implementation of port operations. To use this implementation,
  1475. do the following:
  1476. @example
  1477. (use-modules (ice-9 suspendable-ports))
  1478. (install-suspendable-ports!)
  1479. @end example
  1480. This will replace the core I/O primitives like @code{get-char} and
  1481. @code{put-bytevector} with new versions that are exactly the same as the
  1482. ones in the standard library, but with two differences. One is that
  1483. when a read or a write would block, the suspendable port operations call
  1484. out the value of the @code{current-read-waiter} or
  1485. @code{current-write-waiter} parameter, as appropriate.
  1486. @xref{Parameters}. The default read and write waiters do the same thing
  1487. that the C read and write waiters do, which is to poll. User code can
  1488. parameterize the waiters, though, enabling the computation to suspend
  1489. and allow the program to process other I/O operations. Because the new
  1490. suspendable ports implementation is written in Scheme, that suspended
  1491. computation can resume again later when it is able to make progress.
  1492. Success!
  1493. The other main difference is that because the new ports implementation
  1494. is written in Scheme, it is slower than C, currently by a factor of 3 or
  1495. 4, though it depends on many factors. For this reason we have to keep
  1496. the C implementations as the default ones. One day when Guile's
  1497. compiler is better, we can close this gap and have only one port
  1498. operation implementation again.
  1499. Note that Guile does not currently include an implementation of the
  1500. facility to suspend the current thread and schedule other threads in the
  1501. meantime. Before adding such a thing, we want to make sure that we're
  1502. providing the right primitives that can be used to build schedulers and
  1503. other user-space concurrency patterns, and that the patterns that we
  1504. settle on are the right patterns. In the meantime, have a look at 8sync
  1505. (@url{https://gnu.org/software/8sync}) for a prototype of an
  1506. asynchronous I/O and concurrency facility.
  1507. @deffn {Scheme Procedure} install-suspendable-ports!
  1508. Replace the core ports implementation with suspendable ports, as
  1509. described above. This will mutate the values of the bindings like
  1510. @code{get-char}, @code{put-u8}, and so on in place.
  1511. @end deffn
  1512. @deffn {Scheme Procedure} uninstall-suspendable-ports!
  1513. Restore the original core ports implementation, un-doing the effect of
  1514. @code{install-suspendable-ports!}.
  1515. @end deffn
  1516. @deffn {Scheme Parameter} current-read-waiter
  1517. @deffnx {Scheme Parameter} current-write-waiter
  1518. Parameters whose values are procedures of one argument, called when a
  1519. suspendable port operation would block on a port while reading or
  1520. writing, respectively. The default values of these parameters do a
  1521. blocking @code{poll} on the port's file descriptor. The procedures are
  1522. passed the port in question as their one argument.
  1523. @end deffn
  1524. @node BOM Handling
  1525. @subsection Handling of Unicode Byte Order Marks
  1526. @cindex BOM
  1527. @cindex byte order mark
  1528. This section documents the finer points of Guile's handling of Unicode
  1529. byte order marks (BOMs). A byte order mark (U+FEFF) is typically found
  1530. at the start of a UTF-16 or UTF-32 stream, to allow readers to reliably
  1531. determine the byte order. Occasionally, a BOM is found at the start of
  1532. a UTF-8 stream, but this is much less common and not generally
  1533. recommended.
  1534. Guile attempts to handle BOMs automatically, and in accordance with the
  1535. recommendations of the Unicode Standard, when the port encoding is set
  1536. to @code{UTF-8}, @code{UTF-16}, or @code{UTF-32}. In brief, Guile
  1537. automatically writes a BOM at the start of a UTF-16 or UTF-32 stream,
  1538. and automatically consumes one from the start of a UTF-8, UTF-16, or
  1539. UTF-32 stream.
  1540. As specified in the Unicode Standard, a BOM is only handled specially at
  1541. the start of a stream, and only if the port encoding is set to
  1542. @code{UTF-8}, @code{UTF-16} or @code{UTF-32}. If the port encoding is
  1543. set to @code{UTF-16BE}, @code{UTF-16LE}, @code{UTF-32BE}, or
  1544. @code{UTF-32LE}, then BOMs are @emph{not} handled specially, and none of
  1545. the special handling described in this section applies.
  1546. @itemize @bullet
  1547. @item
  1548. To ensure that Guile will properly detect the byte order of a UTF-16 or
  1549. UTF-32 stream, you must perform a textual read before any writes, seeks,
  1550. or binary I/O. Guile will not attempt to read a BOM unless a read is
  1551. explicitly requested at the start of the stream.
  1552. @item
  1553. If a textual write is performed before the first read, then an arbitrary
  1554. byte order will be chosen. Currently, big endian is the default on all
  1555. platforms, but that may change in the future. If you wish to explicitly
  1556. control the byte order of an output stream, set the port encoding to
  1557. @code{UTF-16BE}, @code{UTF-16LE}, @code{UTF-32BE}, or @code{UTF-32LE},
  1558. and explicitly write a BOM (@code{#\xFEFF}) if desired.
  1559. @item
  1560. If @code{set-port-encoding!} is called in the middle of a stream, Guile
  1561. treats this as a new logical ``start of stream'' for purposes of BOM
  1562. handling, and will forget about any BOMs that had previously been seen.
  1563. Therefore, it may choose a different byte order than had been used
  1564. previously. This is intended to support multiple logical text streams
  1565. embedded within a larger binary stream.
  1566. @item
  1567. Binary I/O operations are not guaranteed to update Guile's notion of
  1568. whether the port is at the ``start of the stream'', nor are they
  1569. guaranteed to produce or consume BOMs.
  1570. @item
  1571. For ports that support seeking (e.g. normal files), the input and output
  1572. streams are considered linked: if the user reads first, then a BOM will
  1573. be consumed (if appropriate), but later writes will @emph{not} produce a
  1574. BOM. Similarly, if the user writes first, then later reads will
  1575. @emph{not} consume a BOM.
  1576. @item
  1577. For ports that are not random access (e.g. pipes, sockets, and
  1578. terminals), the input and output streams are considered
  1579. @emph{independent} for purposes of BOM handling: the first read will
  1580. consume a BOM (if appropriate), and the first write will @emph{also}
  1581. produce a BOM (if appropriate). However, the input and output streams
  1582. will always use the same byte order.
  1583. @item
  1584. Seeks to the beginning of a file will set the ``start of stream'' flags.
  1585. Therefore, a subsequent textual read or write will consume or produce a
  1586. BOM. However, unlike @code{set-port-encoding!}, if a byte order had
  1587. already been chosen for the port, it will remain in effect after a seek,
  1588. and cannot be changed by the presence of a BOM. Seeks anywhere other
  1589. than the beginning of a file clear the ``start of stream'' flags.
  1590. @end itemize
  1591. @c Local Variables:
  1592. @c TeX-master: "guile.texi"
  1593. @c End: