posix.texi 124 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523
  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, 2006, 2007,
  4. @c 2008, 2009, 2010, 2011, 2012 Free Software Foundation, Inc.
  5. @c See the file guile.texi for copying conditions.
  6. @node POSIX
  7. @section @acronym{POSIX} System Calls and Networking
  8. @cindex POSIX
  9. @menu
  10. * Conventions:: Conventions employed by the POSIX interface.
  11. * Ports and File Descriptors:: Scheme ``ports'' and Unix file descriptors
  12. have different representations.
  13. * File System:: stat, chown, chmod, etc.
  14. * User Information:: Retrieving a user's GECOS (/etc/passwd) entry.
  15. * Time:: gettimeofday, localtime, strftime, etc.
  16. * Runtime Environment:: Accessing and modifying Guile's environment.
  17. * Processes:: getuid, getpid, etc.
  18. * Signals:: sigaction, kill, pause, alarm, setitimer, etc.
  19. * Terminals and Ptys:: ttyname, tcsetpgrp, etc.
  20. * Pipes:: Communicating data between processes.
  21. * Networking:: gethostbyaddr, getnetent, socket, bind, listen.
  22. * System Identification:: Obtaining information about the system.
  23. * Locales:: setlocale, etc.
  24. * Encryption::
  25. @end menu
  26. @node Conventions
  27. @subsection @acronym{POSIX} Interface Conventions
  28. These interfaces provide access to operating system facilities.
  29. They provide a simple wrapping around the underlying C interfaces
  30. to make usage from Scheme more convenient. They are also used
  31. to implement the Guile port of scsh (@pxref{The Scheme shell (scsh)}).
  32. Generally there is a single procedure for each corresponding Unix
  33. facility. There are some exceptions, such as procedures implemented for
  34. speed and convenience in Scheme with no primitive Unix equivalent,
  35. e.g.@: @code{copy-file}.
  36. The interfaces are intended as far as possible to be portable across
  37. different versions of Unix. In some cases procedures which can't be
  38. implemented on particular systems may become no-ops, or perform limited
  39. actions. In other cases they may throw errors.
  40. General naming conventions are as follows:
  41. @itemize @bullet
  42. @item
  43. The Scheme name is often identical to the name of the underlying Unix
  44. facility.
  45. @item
  46. Underscores in Unix procedure names are converted to hyphens.
  47. @item
  48. Procedures which destructively modify Scheme data have exclamation
  49. marks appended, e.g., @code{recv!}.
  50. @item
  51. Predicates (returning only @code{#t} or @code{#f}) have question marks
  52. appended, e.g., @code{access?}.
  53. @item
  54. Some names are changed to avoid conflict with dissimilar interfaces
  55. defined by scsh, e.g., @code{primitive-fork}.
  56. @item
  57. Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted
  58. to Scheme variables of the same name (underscores are not replaced
  59. with hyphens).
  60. @end itemize
  61. Unexpected conditions are generally handled by raising exceptions.
  62. There are a few procedures which return a special value if they don't
  63. succeed, e.g., @code{getenv} returns @code{#f} if it the requested
  64. string is not found in the environment. These cases are noted in
  65. the documentation.
  66. For ways to deal with exceptions, see @ref{Exceptions}.
  67. @cindex @code{errno}
  68. Errors which the C library would report by returning a null pointer or
  69. through some other means are reported by raising a @code{system-error}
  70. exception with @code{scm-error} (@pxref{Error Reporting}). The
  71. @var{data} parameter is a list containing the Unix @code{errno} value
  72. (an integer). For example,
  73. @example
  74. (define (my-handler key func fmt fmtargs data)
  75. (display key) (newline)
  76. (display func) (newline)
  77. (apply format #t fmt fmtargs) (newline)
  78. (display data) (newline))
  79. (catch 'system-error
  80. (lambda () (dup2 -123 -456))
  81. my-handler)
  82. @print{}
  83. system-error
  84. dup2
  85. Bad file descriptor
  86. (9)
  87. @end example
  88. @sp 1
  89. @defun system-error-errno arglist
  90. @cindex @code{errno}
  91. Return the @code{errno} value from a list which is the arguments to an
  92. exception handler. If the exception is not a @code{system-error},
  93. then the return is @code{#f}. For example,
  94. @example
  95. (catch
  96. 'system-error
  97. (lambda ()
  98. (mkdir "/this-ought-to-fail-if-I'm-not-root"))
  99. (lambda stuff
  100. (let ((errno (system-error-errno stuff)))
  101. (cond
  102. ((= errno EACCES)
  103. (display "You're not allowed to do that."))
  104. ((= errno EEXIST)
  105. (display "Already exists."))
  106. (#t
  107. (display (strerror errno))))
  108. (newline))))
  109. @end example
  110. @end defun
  111. @node Ports and File Descriptors
  112. @subsection Ports and File Descriptors
  113. @cindex file descriptor
  114. Conventions generally follow those of scsh, @ref{The Scheme shell (scsh)}.
  115. File ports are implemented using low-level operating system I/O
  116. facilities, with optional buffering to improve efficiency; see
  117. @ref{File Ports}.
  118. Note that some procedures (e.g., @code{recv!}) will accept ports as
  119. arguments, but will actually operate directly on the file descriptor
  120. underlying the port. Any port buffering is ignored, including the
  121. buffer which implements @code{peek-char} and @code{unread-char}.
  122. The @code{force-output} and @code{drain-input} procedures can be used
  123. to clear the buffers.
  124. Each open file port has an associated operating system file descriptor.
  125. File descriptors are generally not useful in Scheme programs; however
  126. they may be needed when interfacing with foreign code and the Unix
  127. environment.
  128. A file descriptor can be extracted from a port and a new port can be
  129. created from a file descriptor. However a file descriptor is just an
  130. integer and the garbage collector doesn't recognize it as a reference
  131. to the port. If all other references to the port were dropped, then
  132. it's likely that the garbage collector would free the port, with the
  133. side-effect of closing the file descriptor prematurely.
  134. To assist the programmer in avoiding this problem, each port has an
  135. associated @dfn{revealed count} which can be used to keep track of how many
  136. times the underlying file descriptor has been stored in other places.
  137. If a port's revealed count is greater than zero, the file descriptor
  138. will not be closed when the port is garbage collected. A programmer
  139. can therefore ensure that the revealed count will be greater than
  140. zero if the file descriptor is needed elsewhere.
  141. For the simple case where a file descriptor is ``imported'' once to become
  142. a port, it does not matter if the file descriptor is closed when the
  143. port is garbage collected. There is no need to maintain a revealed
  144. count. Likewise when ``exporting'' a file descriptor to the external
  145. environment, setting the revealed count is not required provided the
  146. port is kept open (i.e., is pointed to by a live Scheme binding) while
  147. the file descriptor is in use.
  148. To correspond with traditional Unix behaviour, three file descriptors
  149. (0, 1, and 2) are automatically imported when a program starts up and
  150. assigned to the initial values of the current/standard input, output,
  151. and error ports, respectively. The revealed count for each is
  152. initially set to one, so that dropping references to one of these
  153. ports will not result in its garbage collection: it could be retrieved
  154. with @code{fdopen} or @code{fdes->ports}.
  155. @deffn {Scheme Procedure} port-revealed port
  156. @deffnx {C Function} scm_port_revealed (port)
  157. Return the revealed count for @var{port}.
  158. @end deffn
  159. @deffn {Scheme Procedure} set-port-revealed! port rcount
  160. @deffnx {C Function} scm_set_port_revealed_x (port, rcount)
  161. Sets the revealed count for a @var{port} to @var{rcount}.
  162. The return value is unspecified.
  163. @end deffn
  164. @deffn {Scheme Procedure} fileno port
  165. @deffnx {C Function} scm_fileno (port)
  166. Return the integer file descriptor underlying @var{port}. Does
  167. not change its revealed count.
  168. @end deffn
  169. @deffn {Scheme Procedure} port->fdes port
  170. Returns the integer file descriptor underlying @var{port}. As a
  171. side effect the revealed count of @var{port} is incremented.
  172. @end deffn
  173. @deffn {Scheme Procedure} fdopen fdes modes
  174. @deffnx {C Function} scm_fdopen (fdes, modes)
  175. Return a new port based on the file descriptor @var{fdes}. Modes are
  176. given by the string @var{modes}. The revealed count of the port is
  177. initialized to zero. The @var{modes} string is the same as that
  178. accepted by @code{open-file} (@pxref{File Ports, open-file}).
  179. @end deffn
  180. @deffn {Scheme Procedure} fdes->ports fdes
  181. @deffnx {C Function} scm_fdes_to_ports (fdes)
  182. Return a list of existing ports which have @var{fdes} as an
  183. underlying file descriptor, without changing their revealed
  184. counts.
  185. @end deffn
  186. @deffn {Scheme Procedure} fdes->inport fdes
  187. Returns an existing input port which has @var{fdes} as its underlying file
  188. descriptor, if one exists, and increments its revealed count.
  189. Otherwise, returns a new input port with a revealed count of 1.
  190. @end deffn
  191. @deffn {Scheme Procedure} fdes->outport fdes
  192. Returns an existing output port which has @var{fdes} as its underlying file
  193. descriptor, if one exists, and increments its revealed count.
  194. Otherwise, returns a new output port with a revealed count of 1.
  195. @end deffn
  196. @deffn {Scheme Procedure} primitive-move->fdes port fdes
  197. @deffnx {C Function} scm_primitive_move_to_fdes (port, fdes)
  198. Moves the underlying file descriptor for @var{port} to the integer
  199. value @var{fdes} without changing the revealed count of @var{port}.
  200. Any other ports already using this descriptor will be automatically
  201. shifted to new descriptors and their revealed counts reset to zero.
  202. The return value is @code{#f} if the file descriptor already had the
  203. required value or @code{#t} if it was moved.
  204. @end deffn
  205. @deffn {Scheme Procedure} move->fdes port fdes
  206. Moves the underlying file descriptor for @var{port} to the integer
  207. value @var{fdes} and sets its revealed count to one. Any other ports
  208. already using this descriptor will be automatically
  209. shifted to new descriptors and their revealed counts reset to zero.
  210. The return value is unspecified.
  211. @end deffn
  212. @deffn {Scheme Procedure} release-port-handle port
  213. Decrements the revealed count for a port.
  214. @end deffn
  215. @deffn {Scheme Procedure} fsync port_or_fd
  216. @deffnx {C Function} scm_fsync (port_or_fd)
  217. Copies any unwritten data for the specified output file descriptor to disk.
  218. If @var{port_or_fd} is a port, its buffer is flushed before the underlying
  219. file descriptor is fsync'd.
  220. The return value is unspecified.
  221. @end deffn
  222. @deffn {Scheme Procedure} open path flags [mode]
  223. @deffnx {C Function} scm_open (path, flags, mode)
  224. Open the file named by @var{path} for reading and/or writing.
  225. @var{flags} is an integer specifying how the file should be opened.
  226. @var{mode} is an integer specifying the permission bits of the file,
  227. if it needs to be created, before the umask (@pxref{Processes}) is
  228. applied. The default is 666 (Unix itself has no default).
  229. @var{flags} can be constructed by combining variables using @code{logior}.
  230. Basic flags are:
  231. @defvar O_RDONLY
  232. Open the file read-only.
  233. @end defvar
  234. @defvar O_WRONLY
  235. Open the file write-only.
  236. @end defvar
  237. @defvar O_RDWR
  238. Open the file read/write.
  239. @end defvar
  240. @defvar O_APPEND
  241. Append to the file instead of truncating.
  242. @end defvar
  243. @defvar O_CREAT
  244. Create the file if it does not already exist.
  245. @end defvar
  246. @xref{File Status Flags,,,libc,The GNU C Library Reference Manual},
  247. for additional flags.
  248. @end deffn
  249. @deffn {Scheme Procedure} open-fdes path flags [mode]
  250. @deffnx {C Function} scm_open_fdes (path, flags, mode)
  251. Similar to @code{open} but return a file descriptor instead of
  252. a port.
  253. @end deffn
  254. @deffn {Scheme Procedure} close fd_or_port
  255. @deffnx {C Function} scm_close (fd_or_port)
  256. Similar to @code{close-port} (@pxref{Closing, close-port}),
  257. but also works on file descriptors. A side
  258. effect of closing a file descriptor is that any ports using that file
  259. descriptor are moved to a different file descriptor and have
  260. their revealed counts set to zero.
  261. @end deffn
  262. @deffn {Scheme Procedure} close-fdes fd
  263. @deffnx {C Function} scm_close_fdes (fd)
  264. A simple wrapper for the @code{close} system call. Close file
  265. descriptor @var{fd}, which must be an integer. Unlike @code{close},
  266. the file descriptor will be closed even if a port is using it. The
  267. return value is unspecified.
  268. @end deffn
  269. @deffn {Scheme Procedure} unread-char char [port]
  270. @deffnx {C Function} scm_unread_char (char, port)
  271. Place @var{char} in @var{port} so that it will be read by the next
  272. read operation on that port. If called multiple times, the unread
  273. characters will be read again in ``last-in, first-out'' order (i.e.@:
  274. a stack). If @var{port} is not supplied, the current input port is
  275. used.
  276. @end deffn
  277. @deffn {Scheme Procedure} unread-string str port
  278. Place the string @var{str} in @var{port} so that its characters will be
  279. read in subsequent read operations. If called multiple times, the
  280. unread characters will be read again in last-in first-out order. If
  281. @var{port} is not supplied, the current-input-port is used.
  282. @end deffn
  283. @deffn {Scheme Procedure} pipe
  284. @deffnx {C Function} scm_pipe ()
  285. @cindex pipe
  286. Return a newly created pipe: a pair of ports which are linked
  287. together on the local machine. The @acronym{CAR} is the input
  288. port and the @acronym{CDR} is the output port. Data written (and
  289. flushed) to the output port can be read from the input port.
  290. Pipes are commonly used for communication with a newly forked
  291. child process. The need to flush the output port can be
  292. avoided by making it unbuffered using @code{setvbuf}.
  293. @defvar PIPE_BUF
  294. A write of up to @code{PIPE_BUF} many bytes to a pipe is atomic,
  295. meaning when done it goes into the pipe instantaneously and as a
  296. contiguous block (@pxref{Pipe Atomicity,, Atomicity of Pipe I/O, libc,
  297. The GNU C Library Reference Manual}).
  298. @end defvar
  299. Note that the output port is likely to block if too much data has been
  300. written but not yet read from the input port. Typically the capacity
  301. is @code{PIPE_BUF} bytes.
  302. @end deffn
  303. The next group of procedures perform a @code{dup2}
  304. system call, if @var{newfd} (an
  305. integer) is supplied, otherwise a @code{dup}. The file descriptor to be
  306. duplicated can be supplied as an integer or contained in a port. The
  307. type of value returned varies depending on which procedure is used.
  308. All procedures also have the side effect when performing @code{dup2} that any
  309. ports using @var{newfd} are moved to a different file descriptor and have
  310. their revealed counts set to zero.
  311. @deffn {Scheme Procedure} dup->fdes fd_or_port [fd]
  312. @deffnx {C Function} scm_dup_to_fdes (fd_or_port, fd)
  313. Return a new integer file descriptor referring to the open file
  314. designated by @var{fd_or_port}, which must be either an open
  315. file port or a file descriptor.
  316. @end deffn
  317. @deffn {Scheme Procedure} dup->inport port/fd [newfd]
  318. Returns a new input port using the new file descriptor.
  319. @end deffn
  320. @deffn {Scheme Procedure} dup->outport port/fd [newfd]
  321. Returns a new output port using the new file descriptor.
  322. @end deffn
  323. @deffn {Scheme Procedure} dup port/fd [newfd]
  324. Returns a new port if @var{port/fd} is a port, with the same mode as the
  325. supplied port, otherwise returns an integer file descriptor.
  326. @end deffn
  327. @deffn {Scheme Procedure} dup->port port/fd mode [newfd]
  328. Returns a new port using the new file descriptor. @var{mode} supplies a
  329. mode string for the port (@pxref{File Ports, open-file}).
  330. @end deffn
  331. @deffn {Scheme Procedure} duplicate-port port modes
  332. Returns a new port which is opened on a duplicate of the file
  333. descriptor underlying @var{port}, with mode string @var{modes}
  334. as for @ref{File Ports, open-file}. The two ports
  335. will share a file position and file status flags.
  336. Unexpected behaviour can result if both ports are subsequently used
  337. and the original and/or duplicate ports are buffered.
  338. The mode string can include @code{0} to obtain an unbuffered duplicate
  339. port.
  340. This procedure is equivalent to @code{(dup->port @var{port} @var{modes})}.
  341. @end deffn
  342. @deffn {Scheme Procedure} redirect-port old_port new_port
  343. @deffnx {C Function} scm_redirect_port (old_port, new_port)
  344. This procedure takes two ports and duplicates the underlying file
  345. descriptor from @var{old_port} into @var{new_port}. The
  346. current file descriptor in @var{new_port} will be closed.
  347. After the redirection the two ports will share a file position
  348. and file status flags.
  349. The return value is unspecified.
  350. Unexpected behaviour can result if both ports are subsequently used
  351. and the original and/or duplicate ports are buffered.
  352. This procedure does not have any side effects on other ports or
  353. revealed counts.
  354. @end deffn
  355. @deffn {Scheme Procedure} dup2 oldfd newfd
  356. @deffnx {C Function} scm_dup2 (oldfd, newfd)
  357. A simple wrapper for the @code{dup2} system call.
  358. Copies the file descriptor @var{oldfd} to descriptor
  359. number @var{newfd}, replacing the previous meaning
  360. of @var{newfd}. Both @var{oldfd} and @var{newfd} must
  361. be integers.
  362. Unlike for @code{dup->fdes} or @code{primitive-move->fdes}, no attempt
  363. is made to move away ports which are using @var{newfd}.
  364. The return value is unspecified.
  365. @end deffn
  366. @deffn {Scheme Procedure} port-mode port
  367. Return the port modes associated with the open port @var{port}.
  368. These will not necessarily be identical to the modes used when
  369. the port was opened, since modes such as ``append'' which are
  370. used only during port creation are not retained.
  371. @end deffn
  372. @deffn {Scheme Procedure} port-for-each proc
  373. @deffnx {C Function} scm_port_for_each (SCM proc)
  374. @deffnx {C Function} scm_c_port_for_each (void (*proc)(void *, SCM), void *data)
  375. Apply @var{proc} to each port in the Guile port table
  376. (FIXME: what is the Guile port table?)
  377. in turn. The return value is unspecified. More specifically,
  378. @var{proc} is applied exactly once to every port that exists in the
  379. system at the time @code{port-for-each} is invoked. Changes to the
  380. port table while @code{port-for-each} is running have no effect as far
  381. as @code{port-for-each} is concerned.
  382. The C function @code{scm_port_for_each} takes a Scheme procedure
  383. encoded as a @code{SCM} value, while @code{scm_c_port_for_each} takes
  384. a pointer to a C function and passes along a arbitrary @var{data}
  385. cookie.
  386. @end deffn
  387. @deffn {Scheme Procedure} setvbuf port mode [size]
  388. @deffnx {C Function} scm_setvbuf (port, mode, size)
  389. @cindex port buffering
  390. Set the buffering mode for @var{port}. @var{mode} can be:
  391. @defvar _IONBF
  392. non-buffered
  393. @end defvar
  394. @defvar _IOLBF
  395. line buffered
  396. @end defvar
  397. @defvar _IOFBF
  398. block buffered, using a newly allocated buffer of @var{size} bytes.
  399. If @var{size} is omitted, a default size will be used.
  400. @end defvar
  401. @end deffn
  402. @deffn {Scheme Procedure} fcntl port/fd cmd [value]
  403. @deffnx {C Function} scm_fcntl (object, cmd, value)
  404. Apply @var{cmd} on @var{port/fd}, either a port or file descriptor.
  405. The @var{value} argument is used by the @code{SET} commands described
  406. below, it's an integer value.
  407. Values for @var{cmd} are:
  408. @defvar F_DUPFD
  409. Duplicate the file descriptor, the same as @code{dup->fdes} above
  410. does.
  411. @end defvar
  412. @defvar F_GETFD
  413. @defvarx F_SETFD
  414. Get or set flags associated with the file descriptor. The only flag
  415. is the following,
  416. @defvar FD_CLOEXEC
  417. ``Close on exec'', meaning the file descriptor will be closed on an
  418. @code{exec} call (a successful such call). For example to set that
  419. flag,
  420. @example
  421. (fcntl port F_SETFD FD_CLOEXEC)
  422. @end example
  423. Or better, set it but leave any other possible future flags unchanged,
  424. @example
  425. (fcntl port F_SETFD (logior FD_CLOEXEC
  426. (fcntl port F_GETFD)))
  427. @end example
  428. @end defvar
  429. @end defvar
  430. @defvar F_GETFL
  431. @defvarx F_SETFL
  432. Get or set flags associated with the open file. These flags are
  433. @code{O_RDONLY} etc described under @code{open} above.
  434. A common use is to set @code{O_NONBLOCK} on a network socket. The
  435. following sets that flag, and leaves other flags unchanged.
  436. @example
  437. (fcntl sock F_SETFL (logior O_NONBLOCK
  438. (fcntl sock F_GETFL)))
  439. @end example
  440. @end defvar
  441. @defvar F_GETOWN
  442. @defvarx F_SETOWN
  443. Get or set the process ID of a socket's owner, for @code{SIGIO} signals.
  444. @end defvar
  445. @end deffn
  446. @deffn {Scheme Procedure} flock file operation
  447. @deffnx {C Function} scm_flock (file, operation)
  448. @cindex file locking
  449. Apply or remove an advisory lock on an open file.
  450. @var{operation} specifies the action to be done:
  451. @defvar LOCK_SH
  452. Shared lock. More than one process may hold a shared lock
  453. for a given file at a given time.
  454. @end defvar
  455. @defvar LOCK_EX
  456. Exclusive lock. Only one process may hold an exclusive lock
  457. for a given file at a given time.
  458. @end defvar
  459. @defvar LOCK_UN
  460. Unlock the file.
  461. @end defvar
  462. @defvar LOCK_NB
  463. Don't block when locking. This is combined with one of the other
  464. operations using @code{logior} (@pxref{Bitwise Operations}). If
  465. @code{flock} would block an @code{EWOULDBLOCK} error is thrown
  466. (@pxref{Conventions}).
  467. @end defvar
  468. The return value is not specified. @var{file} may be an open
  469. file descriptor or an open file descriptor port.
  470. Note that @code{flock} does not lock files across NFS.
  471. @end deffn
  472. @deffn {Scheme Procedure} select reads writes excepts [secs [usecs]]
  473. @deffnx {C Function} scm_select (reads, writes, excepts, secs, usecs)
  474. This procedure has a variety of uses: waiting for the ability
  475. to provide input, accept output, or the existence of
  476. exceptional conditions on a collection of ports or file
  477. descriptors, or waiting for a timeout to occur.
  478. It also returns if interrupted by a signal.
  479. @var{reads}, @var{writes} and @var{excepts} can be lists or
  480. vectors, with each member a port or a file descriptor.
  481. The value returned is a list of three corresponding
  482. lists or vectors containing only the members which meet the
  483. specified requirement. The ability of port buffers to
  484. provide input or accept output is taken into account.
  485. Ordering of the input lists or vectors is not preserved.
  486. The optional arguments @var{secs} and @var{usecs} specify the
  487. timeout. Either @var{secs} can be specified alone, as
  488. either an integer or a real number, or both @var{secs} and
  489. @var{usecs} can be specified as integers, in which case
  490. @var{usecs} is an additional timeout expressed in
  491. microseconds. If @var{secs} is omitted or is @code{#f} then
  492. select will wait for as long as it takes for one of the other
  493. conditions to be satisfied.
  494. The scsh version of @code{select} differs as follows:
  495. Only vectors are accepted for the first three arguments.
  496. The @var{usecs} argument is not supported.
  497. Multiple values are returned instead of a list.
  498. Duplicates in the input vectors appear only once in output.
  499. An additional @code{select!} interface is provided.
  500. @end deffn
  501. @node File System
  502. @subsection File System
  503. @cindex file system
  504. These procedures allow querying and setting file system attributes
  505. (such as owner,
  506. permissions, sizes and types of files); deleting, copying, renaming and
  507. linking files; creating and removing directories and querying their
  508. contents; syncing the file system and creating special files.
  509. @deffn {Scheme Procedure} access? path how
  510. @deffnx {C Function} scm_access (path, how)
  511. Test accessibility of a file under the real UID and GID of the calling
  512. process. The return is @code{#t} if @var{path} exists and the
  513. permissions requested by @var{how} are all allowed, or @code{#f} if
  514. not.
  515. @var{how} is an integer which is one of the following values, or a
  516. bitwise-OR (@code{logior}) of multiple values.
  517. @defvar R_OK
  518. Test for read permission.
  519. @end defvar
  520. @defvar W_OK
  521. Test for write permission.
  522. @end defvar
  523. @defvar X_OK
  524. Test for execute permission.
  525. @end defvar
  526. @defvar F_OK
  527. Test for existence of the file. This is implied by each of the other
  528. tests, so there's no need to combine it with them.
  529. @end defvar
  530. It's important to note that @code{access?} does not simply indicate
  531. what will happen on attempting to read or write a file. In normal
  532. circumstances it does, but in a set-UID or set-GID program it doesn't
  533. because @code{access?} tests the real ID, whereas an open or execute
  534. attempt uses the effective ID.
  535. A program which will never run set-UID/GID can ignore the difference
  536. between real and effective IDs, but for maximum generality, especially
  537. in library functions, it's best not to use @code{access?} to predict
  538. the result of an open or execute, instead simply attempt that and
  539. catch any exception.
  540. The main use for @code{access?} is to let a set-UID/GID program
  541. determine what the invoking user would have been allowed to do,
  542. without the greater (or perhaps lesser) privileges afforded by the
  543. effective ID. For more on this, see @ref{Testing File Access,,, libc,
  544. The GNU C Library Reference Manual}.
  545. @end deffn
  546. @findex fstat
  547. @deffn {Scheme Procedure} stat object
  548. @deffnx {C Function} scm_stat (object)
  549. Return an object containing various information about the file
  550. determined by @var{object}. @var{object} can be a string containing
  551. a file name or a port or integer file descriptor which is open
  552. on a file (in which case @code{fstat} is used as the underlying
  553. system call).
  554. The object returned by @code{stat} can be passed as a single
  555. parameter to the following procedures, all of which return
  556. integers:
  557. @deffn {Scheme Procedure} stat:dev st
  558. The device number containing the file.
  559. @end deffn
  560. @deffn {Scheme Procedure} stat:ino st
  561. The file serial number, which distinguishes this file from all
  562. other files on the same device.
  563. @end deffn
  564. @deffn {Scheme Procedure} stat:mode st
  565. The mode of the file. This is an integer which incorporates file type
  566. information and file permission bits. See also @code{stat:type} and
  567. @code{stat:perms} below.
  568. @end deffn
  569. @deffn {Scheme Procedure} stat:nlink st
  570. The number of hard links to the file.
  571. @end deffn
  572. @deffn {Scheme Procedure} stat:uid st
  573. The user ID of the file's owner.
  574. @end deffn
  575. @deffn {Scheme Procedure} stat:gid st
  576. The group ID of the file.
  577. @end deffn
  578. @deffn {Scheme Procedure} stat:rdev st
  579. Device ID; this entry is defined only for character or block special
  580. files. On some systems this field is not available at all, in which
  581. case @code{stat:rdev} returns @code{#f}.
  582. @end deffn
  583. @deffn {Scheme Procedure} stat:size st
  584. The size of a regular file in bytes.
  585. @end deffn
  586. @deffn {Scheme Procedure} stat:atime st
  587. The last access time for the file, in seconds.
  588. @end deffn
  589. @deffn {Scheme Procedure} stat:mtime st
  590. The last modification time for the file, in seconds.
  591. @end deffn
  592. @deffn {Scheme Procedure} stat:ctime st
  593. The last modification time for the attributes of the file, in seconds.
  594. @end deffn
  595. @deffn {Scheme Procedure} stat:atimensec st
  596. @deffnx {Scheme Procedure} stat:mtimensec st
  597. @deffnx {Scheme Procedure} stat:ctimensec st
  598. The fractional part of a file's access, modification, or attribute modification
  599. time, in nanoseconds. Nanosecond timestamps are only available on some operating
  600. systems and file systems. If Guile cannot retrieve nanosecond-level timestamps
  601. for a file, these fields will be set to 0.
  602. @end deffn
  603. @deffn {Scheme Procedure} stat:blksize st
  604. The optimal block size for reading or writing the file, in bytes. On
  605. some systems this field is not available, in which case
  606. @code{stat:blksize} returns a sensible suggested block size.
  607. @end deffn
  608. @deffn {Scheme Procedure} stat:blocks st
  609. The amount of disk space that the file occupies measured in units of
  610. 512 byte blocks. On some systems this field is not available, in
  611. which case @code{stat:blocks} returns @code{#f}.
  612. @end deffn
  613. In addition, the following procedures return the information
  614. from @code{stat:mode} in a more convenient form:
  615. @deffn {Scheme Procedure} stat:type st
  616. A symbol representing the type of file. Possible values are
  617. @samp{regular}, @samp{directory}, @samp{symlink},
  618. @samp{block-special}, @samp{char-special}, @samp{fifo}, @samp{socket},
  619. and @samp{unknown}.
  620. @end deffn
  621. @deffn {Scheme Procedure} stat:perms st
  622. An integer representing the access permission bits.
  623. @end deffn
  624. @end deffn
  625. @deffn {Scheme Procedure} lstat path
  626. @deffnx {C Function} scm_lstat (path)
  627. Similar to @code{stat}, but does not follow symbolic links, i.e.,
  628. it will return information about a symbolic link itself, not the
  629. file it points to. @var{path} must be a string.
  630. @end deffn
  631. @deffn {Scheme Procedure} readlink path
  632. @deffnx {C Function} scm_readlink (path)
  633. Return the value of the symbolic link named by @var{path} (a
  634. string), i.e., the file that the link points to.
  635. @end deffn
  636. @findex fchown
  637. @findex lchown
  638. @deffn {Scheme Procedure} chown object owner group
  639. @deffnx {C Function} scm_chown (object, owner, group)
  640. Change the ownership and group of the file referred to by @var{object}
  641. to the integer values @var{owner} and @var{group}. @var{object} can
  642. be a string containing a file name or, if the platform supports
  643. @code{fchown} (@pxref{File Owner,,,libc,The GNU C Library Reference
  644. Manual}), a port or integer file descriptor which is open on the file.
  645. The return value is unspecified.
  646. If @var{object} is a symbolic link, either the
  647. ownership of the link or the ownership of the referenced file will be
  648. changed depending on the operating system (lchown is
  649. unsupported at present). If @var{owner} or @var{group} is specified
  650. as @code{-1}, then that ID is not changed.
  651. @end deffn
  652. @findex fchmod
  653. @deffn {Scheme Procedure} chmod object mode
  654. @deffnx {C Function} scm_chmod (object, mode)
  655. Changes the permissions of the file referred to by @var{object}.
  656. @var{object} can be a string containing a file name or a port or integer file
  657. descriptor which is open on a file (in which case @code{fchmod} is used
  658. as the underlying system call).
  659. @var{mode} specifies
  660. the new permissions as a decimal number, e.g., @code{(chmod "foo" #o755)}.
  661. The return value is unspecified.
  662. @end deffn
  663. @deffn {Scheme Procedure} utime pathname [actime [modtime [actimens [modtimens [flags]]]]]
  664. @deffnx {C Function} scm_utime (pathname, actime, modtime, actimens, modtimens, flags)
  665. @code{utime} sets the access and modification times for the
  666. file named by @var{pathname}. If @var{actime} or @var{modtime} is
  667. not supplied, then the current time is used. @var{actime} and
  668. @var{modtime} must be integer time values as returned by the
  669. @code{current-time} procedure.
  670. The optional @var{actimens} and @var{modtimens} are nanoseconds
  671. to add @var{actime} and @var{modtime}. Nanosecond precision is
  672. only supported on some combinations of file systems and operating
  673. systems.
  674. @lisp
  675. (utime "foo" (- (current-time) 3600))
  676. @end lisp
  677. will set the access time to one hour in the past and the
  678. modification time to the current time.
  679. @end deffn
  680. @findex unlink
  681. @deffn {Scheme Procedure} delete-file str
  682. @deffnx {C Function} scm_delete_file (str)
  683. Deletes (or ``unlinks'') the file whose path is specified by
  684. @var{str}.
  685. @end deffn
  686. @deffn {Scheme Procedure} copy-file oldfile newfile
  687. @deffnx {C Function} scm_copy_file (oldfile, newfile)
  688. Copy the file specified by @var{oldfile} to @var{newfile}.
  689. The return value is unspecified.
  690. @end deffn
  691. @findex rename
  692. @deffn {Scheme Procedure} rename-file oldname newname
  693. @deffnx {C Function} scm_rename (oldname, newname)
  694. Renames the file specified by @var{oldname} to @var{newname}.
  695. The return value is unspecified.
  696. @end deffn
  697. @deffn {Scheme Procedure} link oldpath newpath
  698. @deffnx {C Function} scm_link (oldpath, newpath)
  699. Creates a new name @var{newpath} in the file system for the
  700. file named by @var{oldpath}. If @var{oldpath} is a symbolic
  701. link, the link may or may not be followed depending on the
  702. system.
  703. @end deffn
  704. @deffn {Scheme Procedure} symlink oldpath newpath
  705. @deffnx {C Function} scm_symlink (oldpath, newpath)
  706. Create a symbolic link named @var{newpath} with the value (i.e., pointing to)
  707. @var{oldpath}. The return value is unspecified.
  708. @end deffn
  709. @deffn {Scheme Procedure} mkdir path [mode]
  710. @deffnx {C Function} scm_mkdir (path, mode)
  711. Create a new directory named by @var{path}. If @var{mode} is omitted
  712. then the permissions of the directory file are set using the current
  713. umask (@pxref{Processes}). Otherwise they are set to the decimal
  714. value specified with @var{mode}. The return value is unspecified.
  715. @end deffn
  716. @deffn {Scheme Procedure} rmdir path
  717. @deffnx {C Function} scm_rmdir (path)
  718. Remove the existing directory named by @var{path}. The directory must
  719. be empty for this to succeed. The return value is unspecified.
  720. @end deffn
  721. @deffn {Scheme Procedure} opendir dirname
  722. @deffnx {C Function} scm_opendir (dirname)
  723. @cindex directory contents
  724. Open the directory specified by @var{dirname} and return a directory
  725. stream.
  726. Before using this and the procedures below, make sure to see the
  727. higher-level procedures for directory traversal that are available
  728. (@pxref{File Tree Walk}).
  729. @end deffn
  730. @deffn {Scheme Procedure} directory-stream? object
  731. @deffnx {C Function} scm_directory_stream_p (object)
  732. Return a boolean indicating whether @var{object} is a directory
  733. stream as returned by @code{opendir}.
  734. @end deffn
  735. @deffn {Scheme Procedure} readdir stream
  736. @deffnx {C Function} scm_readdir (stream)
  737. Return (as a string) the next directory entry from the directory stream
  738. @var{stream}. If there is no remaining entry to be read then the
  739. end of file object is returned.
  740. @end deffn
  741. @deffn {Scheme Procedure} rewinddir stream
  742. @deffnx {C Function} scm_rewinddir (stream)
  743. Reset the directory port @var{stream} so that the next call to
  744. @code{readdir} will return the first directory entry.
  745. @end deffn
  746. @deffn {Scheme Procedure} closedir stream
  747. @deffnx {C Function} scm_closedir (stream)
  748. Close the directory stream @var{stream}.
  749. The return value is unspecified.
  750. @end deffn
  751. Here is an example showing how to display all the entries in a
  752. directory:
  753. @lisp
  754. (define dir (opendir "/usr/lib"))
  755. (do ((entry (readdir dir) (readdir dir)))
  756. ((eof-object? entry))
  757. (display entry)(newline))
  758. (closedir dir)
  759. @end lisp
  760. @deffn {Scheme Procedure} sync
  761. @deffnx {C Function} scm_sync ()
  762. Flush the operating system disk buffers.
  763. The return value is unspecified.
  764. @end deffn
  765. @deffn {Scheme Procedure} mknod path type perms dev
  766. @deffnx {C Function} scm_mknod (path, type, perms, dev)
  767. @cindex device file
  768. Creates a new special file, such as a file corresponding to a device.
  769. @var{path} specifies the name of the file. @var{type} should be one
  770. of the following symbols: @samp{regular}, @samp{directory},
  771. @samp{symlink}, @samp{block-special}, @samp{char-special},
  772. @samp{fifo}, or @samp{socket}. @var{perms} (an integer) specifies the
  773. file permissions. @var{dev} (an integer) specifies which device the
  774. special file refers to. Its exact interpretation depends on the kind
  775. of special file being created.
  776. E.g.,
  777. @lisp
  778. (mknod "/dev/fd0" 'block-special #o660 (+ (* 2 256) 2))
  779. @end lisp
  780. The return value is unspecified.
  781. @end deffn
  782. @deffn {Scheme Procedure} tmpnam
  783. @deffnx {C Function} scm_tmpnam ()
  784. @cindex temporary file
  785. Return an auto-generated name of a temporary file, a file which
  786. doesn't already exist. The name includes a path, it's usually in
  787. @file{/tmp} but that's system dependent.
  788. Care must be taken when using @code{tmpnam}. In between choosing the
  789. name and creating the file another program might use that name, or an
  790. attacker might even make it a symlink pointing at something important
  791. and causing you to overwrite that.
  792. The safe way is to create the file using @code{open} with
  793. @code{O_EXCL} to avoid any overwriting. A loop can try again with
  794. another name if the file exists (error @code{EEXIST}).
  795. @code{mkstemp!} below does that.
  796. @end deffn
  797. @deffn {Scheme Procedure} mkstemp! tmpl
  798. @deffnx {C Function} scm_mkstemp (tmpl)
  799. @cindex temporary file
  800. Create a new unique file in the file system and return a new buffered
  801. port open for reading and writing to the file.
  802. @var{tmpl} is a string specifying where the file should be created: it
  803. must end with @samp{XXXXXX} and those @samp{X}s will be changed in the
  804. string to return the name of the file. (@code{port-filename} on the
  805. port also gives the name.)
  806. POSIX doesn't specify the permissions mode of the file, on GNU and
  807. most systems it's @code{#o600}. An application can use @code{chmod}
  808. to relax that if desired. For example @code{#o666} less @code{umask},
  809. which is usual for ordinary file creation,
  810. @example
  811. (let ((port (mkstemp! (string-copy "/tmp/myfile-XXXXXX"))))
  812. (chmod port (logand #o666 (lognot (umask))))
  813. ...)
  814. @end example
  815. @end deffn
  816. @deffn {Scheme Procedure} tmpfile
  817. @deffnx {C Function} scm_tmpfile ()
  818. Return an input/output port to a unique temporary file
  819. named using the path prefix @code{P_tmpdir} defined in
  820. @file{stdio.h}.
  821. The file is automatically deleted when the port is closed
  822. or the program terminates.
  823. @end deffn
  824. @deffn {Scheme Procedure} dirname filename
  825. @deffnx {C Function} scm_dirname (filename)
  826. Return the directory name component of the file name
  827. @var{filename}. If @var{filename} does not contain a directory
  828. component, @code{.} is returned.
  829. @end deffn
  830. @deffn {Scheme Procedure} basename filename [suffix]
  831. @deffnx {C Function} scm_basename (filename, suffix)
  832. Return the base name of the file name @var{filename}. The
  833. base name is the file name without any directory components.
  834. If @var{suffix} is provided, and is equal to the end of
  835. @var{basename}, it is removed also.
  836. @lisp
  837. (basename "/tmp/test.xml" ".xml")
  838. @result{} "test"
  839. @end lisp
  840. @end deffn
  841. @deffn {Scheme Procedure} file-exists? filename
  842. Return @code{#t} if the file named @var{filename} exists, @code{#f} if
  843. not.
  844. @end deffn
  845. @node User Information
  846. @subsection User Information
  847. @cindex user information
  848. @cindex password file
  849. @cindex group file
  850. The facilities in this section provide an interface to the user and
  851. group database.
  852. They should be used with care since they are not reentrant.
  853. The following functions accept an object representing user information
  854. and return a selected component:
  855. @deffn {Scheme Procedure} passwd:name pw
  856. The name of the userid.
  857. @end deffn
  858. @deffn {Scheme Procedure} passwd:passwd pw
  859. The encrypted passwd.
  860. @end deffn
  861. @deffn {Scheme Procedure} passwd:uid pw
  862. The user id number.
  863. @end deffn
  864. @deffn {Scheme Procedure} passwd:gid pw
  865. The group id number.
  866. @end deffn
  867. @deffn {Scheme Procedure} passwd:gecos pw
  868. The full name.
  869. @end deffn
  870. @deffn {Scheme Procedure} passwd:dir pw
  871. The home directory.
  872. @end deffn
  873. @deffn {Scheme Procedure} passwd:shell pw
  874. The login shell.
  875. @end deffn
  876. @sp 1
  877. @deffn {Scheme Procedure} getpwuid uid
  878. Look up an integer userid in the user database.
  879. @end deffn
  880. @deffn {Scheme Procedure} getpwnam name
  881. Look up a user name string in the user database.
  882. @end deffn
  883. @deffn {Scheme Procedure} setpwent
  884. Initializes a stream used by @code{getpwent} to read from the user database.
  885. The next use of @code{getpwent} will return the first entry. The
  886. return value is unspecified.
  887. @end deffn
  888. @deffn {Scheme Procedure} getpwent
  889. Read the next entry in the user database stream. The return is a
  890. passwd user object as above, or @code{#f} when no more entries.
  891. @end deffn
  892. @deffn {Scheme Procedure} endpwent
  893. Closes the stream used by @code{getpwent}. The return value is unspecified.
  894. @end deffn
  895. @deffn {Scheme Procedure} setpw [arg]
  896. @deffnx {C Function} scm_setpwent (arg)
  897. If called with a true argument, initialize or reset the password data
  898. stream. Otherwise, close the stream. The @code{setpwent} and
  899. @code{endpwent} procedures are implemented on top of this.
  900. @end deffn
  901. @deffn {Scheme Procedure} getpw [user]
  902. @deffnx {C Function} scm_getpwuid (user)
  903. Look up an entry in the user database. @var{user} can be an integer,
  904. a string, or omitted, giving the behaviour of getpwuid, getpwnam
  905. or getpwent respectively.
  906. @end deffn
  907. The following functions accept an object representing group information
  908. and return a selected component:
  909. @deffn {Scheme Procedure} group:name gr
  910. The group name.
  911. @end deffn
  912. @deffn {Scheme Procedure} group:passwd gr
  913. The encrypted group password.
  914. @end deffn
  915. @deffn {Scheme Procedure} group:gid gr
  916. The group id number.
  917. @end deffn
  918. @deffn {Scheme Procedure} group:mem gr
  919. A list of userids which have this group as a supplementary group.
  920. @end deffn
  921. @sp 1
  922. @deffn {Scheme Procedure} getgrgid gid
  923. Look up an integer group id in the group database.
  924. @end deffn
  925. @deffn {Scheme Procedure} getgrnam name
  926. Look up a group name in the group database.
  927. @end deffn
  928. @deffn {Scheme Procedure} setgrent
  929. Initializes a stream used by @code{getgrent} to read from the group database.
  930. The next use of @code{getgrent} will return the first entry.
  931. The return value is unspecified.
  932. @end deffn
  933. @deffn {Scheme Procedure} getgrent
  934. Return the next entry in the group database, using the stream set by
  935. @code{setgrent}.
  936. @end deffn
  937. @deffn {Scheme Procedure} endgrent
  938. Closes the stream used by @code{getgrent}.
  939. The return value is unspecified.
  940. @end deffn
  941. @deffn {Scheme Procedure} setgr [arg]
  942. @deffnx {C Function} scm_setgrent (arg)
  943. If called with a true argument, initialize or reset the group data
  944. stream. Otherwise, close the stream. The @code{setgrent} and
  945. @code{endgrent} procedures are implemented on top of this.
  946. @end deffn
  947. @deffn {Scheme Procedure} getgr [group]
  948. @deffnx {C Function} scm_getgrgid (group)
  949. Look up an entry in the group database. @var{group} can be an integer,
  950. a string, or omitted, giving the behaviour of getgrgid, getgrnam
  951. or getgrent respectively.
  952. @end deffn
  953. In addition to the accessor procedures for the user database, the
  954. following shortcut procedure is also available.
  955. @deffn {Scheme Procedure} getlogin
  956. @deffnx {C Function} scm_getlogin ()
  957. Return a string containing the name of the user logged in on
  958. the controlling terminal of the process, or @code{#f} if this
  959. information cannot be obtained.
  960. @end deffn
  961. @node Time
  962. @subsection Time
  963. @cindex time
  964. @deffn {Scheme Procedure} current-time
  965. @deffnx {C Function} scm_current_time ()
  966. Return the number of seconds since 1970-01-01 00:00:00 @acronym{UTC},
  967. excluding leap seconds.
  968. @end deffn
  969. @deffn {Scheme Procedure} gettimeofday
  970. @deffnx {C Function} scm_gettimeofday ()
  971. Return a pair containing the number of seconds and microseconds
  972. since 1970-01-01 00:00:00 @acronym{UTC}, excluding leap seconds. Note:
  973. whether true microsecond resolution is available depends on the
  974. operating system.
  975. @end deffn
  976. The following procedures either accept an object representing a broken down
  977. time and return a selected component, or accept an object representing
  978. a broken down time and a value and set the component to the value.
  979. The numbers in parentheses give the usual range.
  980. @deffn {Scheme Procedure} tm:sec tm
  981. @deffnx {Scheme Procedure} set-tm:sec tm val
  982. Seconds (0-59).
  983. @end deffn
  984. @deffn {Scheme Procedure} tm:min tm
  985. @deffnx {Scheme Procedure} set-tm:min tm val
  986. Minutes (0-59).
  987. @end deffn
  988. @deffn {Scheme Procedure} tm:hour tm
  989. @deffnx {Scheme Procedure} set-tm:hour tm val
  990. Hours (0-23).
  991. @end deffn
  992. @deffn {Scheme Procedure} tm:mday tm
  993. @deffnx {Scheme Procedure} set-tm:mday tm val
  994. Day of the month (1-31).
  995. @end deffn
  996. @deffn {Scheme Procedure} tm:mon tm
  997. @deffnx {Scheme Procedure} set-tm:mon tm val
  998. Month (0-11).
  999. @end deffn
  1000. @deffn {Scheme Procedure} tm:year tm
  1001. @deffnx {Scheme Procedure} set-tm:year tm val
  1002. Year (70-), the year minus 1900.
  1003. @end deffn
  1004. @deffn {Scheme Procedure} tm:wday tm
  1005. @deffnx {Scheme Procedure} set-tm:wday tm val
  1006. Day of the week (0-6) with Sunday represented as 0.
  1007. @end deffn
  1008. @deffn {Scheme Procedure} tm:yday tm
  1009. @deffnx {Scheme Procedure} set-tm:yday tm val
  1010. Day of the year (0-364, 365 in leap years).
  1011. @end deffn
  1012. @deffn {Scheme Procedure} tm:isdst tm
  1013. @deffnx {Scheme Procedure} set-tm:isdst tm val
  1014. Daylight saving indicator (0 for ``no'', greater than 0 for ``yes'', less than
  1015. 0 for ``unknown'').
  1016. @end deffn
  1017. @deffn {Scheme Procedure} tm:gmtoff tm
  1018. @deffnx {Scheme Procedure} set-tm:gmtoff tm val
  1019. Time zone offset in seconds west of @acronym{UTC} (-46800 to 43200).
  1020. For example on East coast USA (zone @samp{EST+5}) this would be 18000
  1021. (ie.@: @m{5\times60\times60,5*60*60}) in winter, or 14400
  1022. (ie.@: @m{4\times60\times60,4*60*60}) during daylight savings.
  1023. Note @code{tm:gmtoff} is not the same as @code{tm_gmtoff} in the C
  1024. @code{tm} structure. @code{tm_gmtoff} is seconds east and hence the
  1025. negative of the value here.
  1026. @end deffn
  1027. @deffn {Scheme Procedure} tm:zone tm
  1028. @deffnx {Scheme Procedure} set-tm:zone tm val
  1029. Time zone label (a string), not necessarily unique.
  1030. @end deffn
  1031. @sp 1
  1032. @deffn {Scheme Procedure} localtime time [zone]
  1033. @deffnx {C Function} scm_localtime (time, zone)
  1034. @cindex local time
  1035. Return an object representing the broken down components of
  1036. @var{time}, an integer like the one returned by
  1037. @code{current-time}. The time zone for the calculation is
  1038. optionally specified by @var{zone} (a string), otherwise the
  1039. @env{TZ} environment variable or the system default is used.
  1040. @end deffn
  1041. @deffn {Scheme Procedure} gmtime time
  1042. @deffnx {C Function} scm_gmtime (time)
  1043. Return an object representing the broken down components of
  1044. @var{time}, an integer like the one returned by
  1045. @code{current-time}. The values are calculated for @acronym{UTC}.
  1046. @end deffn
  1047. @deffn {Scheme Procedure} mktime sbd-time [zone]
  1048. @deffnx {C Function} scm_mktime (sbd_time, zone)
  1049. For a broken down time object @var{sbd-time}, return a pair the
  1050. @code{car} of which is an integer time like @code{current-time}, and
  1051. the @code{cdr} of which is a new broken down time with normalized
  1052. fields.
  1053. @var{zone} is a timezone string, or the default is the @env{TZ}
  1054. environment variable or the system default (@pxref{TZ Variable,,
  1055. Specifying the Time Zone with @env{TZ}, libc, GNU C Library Reference
  1056. Manual}). @var{sbd-time} is taken to be in that @var{zone}.
  1057. The following fields of @var{sbd-time} are used: @code{tm:year},
  1058. @code{tm:mon}, @code{tm:mday}, @code{tm:hour}, @code{tm:min},
  1059. @code{tm:sec}, @code{tm:isdst}. The values can be outside their usual
  1060. ranges. For example @code{tm:hour} normally goes up to 23, but a
  1061. value say 33 would mean 9 the following day.
  1062. @code{tm:isdst} in @var{sbd-time} says whether the time given is with
  1063. daylight savings or not. This is ignored if @var{zone} doesn't have
  1064. any daylight savings adjustment amount.
  1065. The broken down time in the return normalizes the values of
  1066. @var{sbd-time} by bringing them into their usual ranges, and using the
  1067. actual daylight savings rule for that time in @var{zone} (which may
  1068. differ from what @var{sbd-time} had). The easiest way to think of
  1069. this is that @var{sbd-time} plus @var{zone} converts to the integer
  1070. UTC time, then a @code{localtime} is applied to get the normal
  1071. presentation of that time, in @var{zone}.
  1072. @end deffn
  1073. @deffn {Scheme Procedure} tzset
  1074. @deffnx {C Function} scm_tzset ()
  1075. Initialize the timezone from the @env{TZ} environment variable
  1076. or the system default. It's not usually necessary to call this procedure
  1077. since it's done automatically by other procedures that depend on the
  1078. timezone.
  1079. @end deffn
  1080. @deffn {Scheme Procedure} strftime format tm
  1081. @deffnx {C Function} scm_strftime (format, tm)
  1082. @cindex time formatting
  1083. Return a string which is broken-down time structure @var{tm} formatted
  1084. according to the given @var{format} string.
  1085. @var{format} contains field specifications introduced by a @samp{%}
  1086. character. See @ref{Formatting Calendar Time,,, libc, The GNU C
  1087. Library Reference Manual}, or @samp{man 3 strftime}, for the available
  1088. formatting.
  1089. @lisp
  1090. (strftime "%c" (localtime (current-time)))
  1091. @result{} "Mon Mar 11 20:17:43 2002"
  1092. @end lisp
  1093. If @code{setlocale} has been called (@pxref{Locales}), month and day
  1094. names are from the current locale and in the locale character set.
  1095. @end deffn
  1096. @deffn {Scheme Procedure} strptime format string
  1097. @deffnx {C Function} scm_strptime (format, string)
  1098. @cindex time parsing
  1099. Performs the reverse action to @code{strftime}, parsing
  1100. @var{string} according to the specification supplied in
  1101. @var{format}. The interpretation of month and day names is
  1102. dependent on the current locale. The value returned is a pair.
  1103. The @acronym{CAR} has an object with time components
  1104. in the form returned by @code{localtime} or @code{gmtime},
  1105. but the time zone components
  1106. are not usefully set.
  1107. The @acronym{CDR} reports the number of characters from @var{string}
  1108. which were used for the conversion.
  1109. @end deffn
  1110. @defvar internal-time-units-per-second
  1111. The value of this variable is the number of time units per second
  1112. reported by the following procedures.
  1113. @end defvar
  1114. @deffn {Scheme Procedure} times
  1115. @deffnx {C Function} scm_times ()
  1116. Return an object with information about real and processor
  1117. time. The following procedures accept such an object as an
  1118. argument and return a selected component:
  1119. @deffn {Scheme Procedure} tms:clock tms
  1120. The current real time, expressed as time units relative to an
  1121. arbitrary base.
  1122. @end deffn
  1123. @deffn {Scheme Procedure} tms:utime tms
  1124. The CPU time units used by the calling process.
  1125. @end deffn
  1126. @deffn {Scheme Procedure} tms:stime tms
  1127. The CPU time units used by the system on behalf of the calling
  1128. process.
  1129. @end deffn
  1130. @deffn {Scheme Procedure} tms:cutime tms
  1131. The CPU time units used by terminated child processes of the
  1132. calling process, whose status has been collected (e.g., using
  1133. @code{waitpid}).
  1134. @end deffn
  1135. @deffn {Scheme Procedure} tms:cstime tms
  1136. Similarly, the CPU times units used by the system on behalf of
  1137. terminated child processes.
  1138. @end deffn
  1139. @end deffn
  1140. @deffn {Scheme Procedure} get-internal-real-time
  1141. @deffnx {C Function} scm_get_internal_real_time ()
  1142. Return the number of time units since the interpreter was
  1143. started.
  1144. @end deffn
  1145. @deffn {Scheme Procedure} get-internal-run-time
  1146. @deffnx {C Function} scm_get_internal_run_time ()
  1147. Return the number of time units of processor time used by the
  1148. interpreter. Both @emph{system} and @emph{user} time are
  1149. included but subprocesses are not.
  1150. @end deffn
  1151. @node Runtime Environment
  1152. @subsection Runtime Environment
  1153. @deffn {Scheme Procedure} program-arguments
  1154. @deffnx {Scheme Procedure} command-line
  1155. @deffnx {Scheme Procedure} set-program-arguments
  1156. @deffnx {C Function} scm_program_arguments ()
  1157. @deffnx {C Function} scm_set_program_arguments_scm (lst)
  1158. @cindex command line
  1159. @cindex program arguments
  1160. Get the command line arguments passed to Guile, or set new arguments.
  1161. The arguments are a list of strings, the first of which is the invoked
  1162. program name. This is just @nicode{"guile"} (or the executable path)
  1163. when run interactively, or it's the script name when running a script
  1164. with @option{-s} (@pxref{Invoking Guile}).
  1165. @example
  1166. guile -L /my/extra/dir -s foo.scm abc def
  1167. (program-arguments) @result{} ("foo.scm" "abc" "def")
  1168. @end example
  1169. @code{set-program-arguments} allows a library module or similar to
  1170. modify the arguments, for example to strip options it recognises,
  1171. leaving the rest for the mainline.
  1172. The argument list is held in a fluid, which means it's separate for
  1173. each thread. Neither the list nor the strings within it are copied at
  1174. any point and normally should not be mutated.
  1175. The two names @code{program-arguments} and @code{command-line} are an
  1176. historical accident, they both do exactly the same thing. The name
  1177. @code{scm_set_program_arguments_scm} has an extra @code{_scm} on the
  1178. end to avoid clashing with the C function below.
  1179. @end deffn
  1180. @deftypefn {C Function} void scm_set_program_arguments (int argc, char **argv, char *first)
  1181. @cindex command line
  1182. @cindex program arguments
  1183. Set the list of command line arguments for @code{program-arguments}
  1184. and @code{command-line} above.
  1185. @var{argv} is an array of null-terminated strings, as in a C
  1186. @code{main} function. @var{argc} is the number of strings in
  1187. @var{argv}, or if it's negative then a @code{NULL} in @var{argv} marks
  1188. its end.
  1189. @var{first} is an extra string put at the start of the arguments, or
  1190. @code{NULL} for no such extra. This is a convenient way to pass the
  1191. program name after advancing @var{argv} to strip option arguments.
  1192. Eg.@:
  1193. @example
  1194. @{
  1195. char *progname = argv[0];
  1196. for (argv++; argv[0] != NULL && argv[0][0] == '-'; argv++)
  1197. @{
  1198. /* munch option ... */
  1199. @}
  1200. /* remaining args for scheme level use */
  1201. scm_set_program_arguments (-1, argv, progname);
  1202. @}
  1203. @end example
  1204. This sort of thing is often done at startup under
  1205. @code{scm_boot_guile} with options handled at the C level removed.
  1206. The given strings are all copied, so the C data is not accessed again
  1207. once @code{scm_set_program_arguments} returns.
  1208. @end deftypefn
  1209. @deffn {Scheme Procedure} getenv name
  1210. @deffnx {C Function} scm_getenv (name)
  1211. @cindex environment
  1212. Looks up the string @var{name} in the current environment. The return
  1213. value is @code{#f} unless a string of the form @code{NAME=VALUE} is
  1214. found, in which case the string @code{VALUE} is returned.
  1215. @end deffn
  1216. @deffn {Scheme Procedure} setenv name value
  1217. Modifies the environment of the current process, which is
  1218. also the default environment inherited by child processes.
  1219. If @var{value} is @code{#f}, then @var{name} is removed from the
  1220. environment. Otherwise, the string @var{name}=@var{value} is added
  1221. to the environment, replacing any existing string with name matching
  1222. @var{name}.
  1223. The return value is unspecified.
  1224. @end deffn
  1225. @deffn {Scheme Procedure} unsetenv name
  1226. Remove variable @var{name} from the environment. The
  1227. name can not contain a @samp{=} character.
  1228. @end deffn
  1229. @deffn {Scheme Procedure} environ [env]
  1230. @deffnx {C Function} scm_environ (env)
  1231. If @var{env} is omitted, return the current environment (in the
  1232. Unix sense) as a list of strings. Otherwise set the current
  1233. environment, which is also the default environment for child
  1234. processes, to the supplied list of strings. Each member of
  1235. @var{env} should be of the form @var{name}=@var{value} and values of
  1236. @var{name} should not be duplicated. If @var{env} is supplied
  1237. then the return value is unspecified.
  1238. @end deffn
  1239. @deffn {Scheme Procedure} putenv str
  1240. @deffnx {C Function} scm_putenv (str)
  1241. Modifies the environment of the current process, which is
  1242. also the default environment inherited by child processes.
  1243. If @var{str} is of the form @code{NAME=VALUE} then it will be written
  1244. directly into the environment, replacing any existing environment string
  1245. with
  1246. name matching @code{NAME}. If @var{str} does not contain an equal
  1247. sign, then any existing string with name matching @var{str} will
  1248. be removed.
  1249. The return value is unspecified.
  1250. @end deffn
  1251. @node Processes
  1252. @subsection Processes
  1253. @cindex processes
  1254. @cindex child processes
  1255. @findex cd
  1256. @deffn {Scheme Procedure} chdir str
  1257. @deffnx {C Function} scm_chdir (str)
  1258. @cindex current directory
  1259. Change the current working directory to @var{str}.
  1260. The return value is unspecified.
  1261. @end deffn
  1262. @findex pwd
  1263. @deffn {Scheme Procedure} getcwd
  1264. @deffnx {C Function} scm_getcwd ()
  1265. Return the name of the current working directory.
  1266. @end deffn
  1267. @deffn {Scheme Procedure} umask [mode]
  1268. @deffnx {C Function} scm_umask (mode)
  1269. If @var{mode} is omitted, returns a decimal number representing the
  1270. current file creation mask. Otherwise the file creation mask is set
  1271. to @var{mode} and the previous value is returned. @xref{Setting
  1272. Permissions,,Assigning File Permissions,libc,The GNU C Library
  1273. Reference Manual}, for more on how to use umasks.
  1274. E.g., @code{(umask #o022)} sets the mask to octal 22/decimal 18.
  1275. @end deffn
  1276. @deffn {Scheme Procedure} chroot path
  1277. @deffnx {C Function} scm_chroot (path)
  1278. Change the root directory to that specified in @var{path}.
  1279. This directory will be used for path names beginning with
  1280. @file{/}. The root directory is inherited by all children
  1281. of the current process. Only the superuser may change the
  1282. root directory.
  1283. @end deffn
  1284. @deffn {Scheme Procedure} getpid
  1285. @deffnx {C Function} scm_getpid ()
  1286. Return an integer representing the current process ID.
  1287. @end deffn
  1288. @deffn {Scheme Procedure} getgroups
  1289. @deffnx {C Function} scm_getgroups ()
  1290. Return a vector of integers representing the current
  1291. supplementary group IDs.
  1292. @end deffn
  1293. @deffn {Scheme Procedure} getppid
  1294. @deffnx {C Function} scm_getppid ()
  1295. Return an integer representing the process ID of the parent
  1296. process.
  1297. @end deffn
  1298. @deffn {Scheme Procedure} getuid
  1299. @deffnx {C Function} scm_getuid ()
  1300. Return an integer representing the current real user ID.
  1301. @end deffn
  1302. @deffn {Scheme Procedure} getgid
  1303. @deffnx {C Function} scm_getgid ()
  1304. Return an integer representing the current real group ID.
  1305. @end deffn
  1306. @deffn {Scheme Procedure} geteuid
  1307. @deffnx {C Function} scm_geteuid ()
  1308. Return an integer representing the current effective user ID.
  1309. If the system does not support effective IDs, then the real ID
  1310. is returned. @code{(provided? 'EIDs)} reports whether the
  1311. system supports effective IDs.
  1312. @end deffn
  1313. @deffn {Scheme Procedure} getegid
  1314. @deffnx {C Function} scm_getegid ()
  1315. Return an integer representing the current effective group ID.
  1316. If the system does not support effective IDs, then the real ID
  1317. is returned. @code{(provided? 'EIDs)} reports whether the
  1318. system supports effective IDs.
  1319. @end deffn
  1320. @deffn {Scheme Procedure} setgroups vec
  1321. @deffnx {C Function} scm_setgroups (vec)
  1322. Set the current set of supplementary group IDs to the integers in the
  1323. given vector @var{vec}. The return value is unspecified.
  1324. Generally only the superuser can set the process group IDs
  1325. (@pxref{Setting Groups, Setting the Group IDs,, libc, The GNU C
  1326. Library Reference Manual}).
  1327. @end deffn
  1328. @deffn {Scheme Procedure} setuid id
  1329. @deffnx {C Function} scm_setuid (id)
  1330. Sets both the real and effective user IDs to the integer @var{id}, provided
  1331. the process has appropriate privileges.
  1332. The return value is unspecified.
  1333. @end deffn
  1334. @deffn {Scheme Procedure} setgid id
  1335. @deffnx {C Function} scm_setgid (id)
  1336. Sets both the real and effective group IDs to the integer @var{id}, provided
  1337. the process has appropriate privileges.
  1338. The return value is unspecified.
  1339. @end deffn
  1340. @deffn {Scheme Procedure} seteuid id
  1341. @deffnx {C Function} scm_seteuid (id)
  1342. Sets the effective user ID to the integer @var{id}, provided the process
  1343. has appropriate privileges. If effective IDs are not supported, the
  1344. real ID is set instead---@code{(provided? 'EIDs)} reports whether the
  1345. system supports effective IDs.
  1346. The return value is unspecified.
  1347. @end deffn
  1348. @deffn {Scheme Procedure} setegid id
  1349. @deffnx {C Function} scm_setegid (id)
  1350. Sets the effective group ID to the integer @var{id}, provided the process
  1351. has appropriate privileges. If effective IDs are not supported, the
  1352. real ID is set instead---@code{(provided? 'EIDs)} reports whether the
  1353. system supports effective IDs.
  1354. The return value is unspecified.
  1355. @end deffn
  1356. @deffn {Scheme Procedure} getpgrp
  1357. @deffnx {C Function} scm_getpgrp ()
  1358. Return an integer representing the current process group ID.
  1359. This is the @acronym{POSIX} definition, not @acronym{BSD}.
  1360. @end deffn
  1361. @deffn {Scheme Procedure} setpgid pid pgid
  1362. @deffnx {C Function} scm_setpgid (pid, pgid)
  1363. Move the process @var{pid} into the process group @var{pgid}. @var{pid} or
  1364. @var{pgid} must be integers: they can be zero to indicate the ID of the
  1365. current process.
  1366. Fails on systems that do not support job control.
  1367. The return value is unspecified.
  1368. @end deffn
  1369. @deffn {Scheme Procedure} setsid
  1370. @deffnx {C Function} scm_setsid ()
  1371. Creates a new session. The current process becomes the session leader
  1372. and is put in a new process group. The process will be detached
  1373. from its controlling terminal if it has one.
  1374. The return value is an integer representing the new process group ID.
  1375. @end deffn
  1376. @deffn {Scheme Procedure} getsid pid
  1377. @deffnx {C Function} scm_getsid (pid)
  1378. Returns the session ID of process @var{pid}. (The session
  1379. ID of a process is the process group ID of its session leader.)
  1380. @end deffn
  1381. @deffn {Scheme Procedure} waitpid pid [options]
  1382. @deffnx {C Function} scm_waitpid (pid, options)
  1383. This procedure collects status information from a child process which
  1384. has terminated or (optionally) stopped. Normally it will
  1385. suspend the calling process until this can be done. If more than one
  1386. child process is eligible then one will be chosen by the operating system.
  1387. The value of @var{pid} determines the behaviour:
  1388. @table @asis
  1389. @item @var{pid} greater than 0
  1390. Request status information from the specified child process.
  1391. @item @var{pid} equal to -1 or @code{WAIT_ANY}
  1392. @vindex WAIT_ANY
  1393. Request status information for any child process.
  1394. @item @var{pid} equal to 0 or @code{WAIT_MYPGRP}
  1395. @vindex WAIT_MYPGRP
  1396. Request status information for any child process in the current process
  1397. group.
  1398. @item @var{pid} less than -1
  1399. Request status information for any child process whose process group ID
  1400. is @minus{}@var{pid}.
  1401. @end table
  1402. The @var{options} argument, if supplied, should be the bitwise OR of the
  1403. values of zero or more of the following variables:
  1404. @defvar WNOHANG
  1405. Return immediately even if there are no child processes to be collected.
  1406. @end defvar
  1407. @defvar WUNTRACED
  1408. Report status information for stopped processes as well as terminated
  1409. processes.
  1410. @end defvar
  1411. The return value is a pair containing:
  1412. @enumerate
  1413. @item
  1414. The process ID of the child process, or 0 if @code{WNOHANG} was
  1415. specified and no process was collected.
  1416. @item
  1417. The integer status value.
  1418. @end enumerate
  1419. @end deffn
  1420. The following three
  1421. functions can be used to decode the process status code returned
  1422. by @code{waitpid}.
  1423. @deffn {Scheme Procedure} status:exit-val status
  1424. @deffnx {C Function} scm_status_exit_val (status)
  1425. Return the exit status value, as would be set if a process
  1426. ended normally through a call to @code{exit} or @code{_exit},
  1427. if any, otherwise @code{#f}.
  1428. @end deffn
  1429. @deffn {Scheme Procedure} status:term-sig status
  1430. @deffnx {C Function} scm_status_term_sig (status)
  1431. Return the signal number which terminated the process, if any,
  1432. otherwise @code{#f}.
  1433. @end deffn
  1434. @deffn {Scheme Procedure} status:stop-sig status
  1435. @deffnx {C Function} scm_status_stop_sig (status)
  1436. Return the signal number which stopped the process, if any,
  1437. otherwise @code{#f}.
  1438. @end deffn
  1439. @deffn {Scheme Procedure} system [cmd]
  1440. @deffnx {C Function} scm_system (cmd)
  1441. Execute @var{cmd} using the operating system's ``command
  1442. processor''. Under Unix this is usually the default shell
  1443. @code{sh}. The value returned is @var{cmd}'s exit status as
  1444. returned by @code{waitpid}, which can be interpreted using the
  1445. functions above.
  1446. If @code{system} is called without arguments, return a boolean
  1447. indicating whether the command processor is available.
  1448. @end deffn
  1449. @deffn {Scheme Procedure} system* arg1 arg2 @dots{}
  1450. @deffnx {C Function} scm_system_star (args)
  1451. Execute the command indicated by @var{arg1} @var{arg2} @enddots{}. The
  1452. first element must be a string indicating the command to be executed,
  1453. and the remaining items must be strings representing each of the
  1454. arguments to that command.
  1455. This function returns the exit status of the command as provided by
  1456. @code{waitpid}. This value can be handled with @code{status:exit-val}
  1457. and the related functions.
  1458. @code{system*} is similar to @code{system}, but accepts only one
  1459. string per-argument, and performs no shell interpretation. The
  1460. command is executed using fork and execlp. Accordingly this function
  1461. may be safer than @code{system} in situations where shell
  1462. interpretation is not required.
  1463. Example: (system* "echo" "foo" "bar")
  1464. @end deffn
  1465. @deffn {Scheme Procedure} primitive-exit [status]
  1466. @deffnx {Scheme Procedure} primitive-_exit [status]
  1467. @deffnx {C Function} scm_primitive_exit (status)
  1468. @deffnx {C Function} scm_primitive__exit (status)
  1469. Terminate the current process without unwinding the Scheme stack. The
  1470. exit status is @var{status} if supplied, otherwise zero.
  1471. @code{primitive-exit} uses the C @code{exit} function and hence runs
  1472. usual C level cleanups (flush output streams, call @code{atexit}
  1473. functions, etc, see @ref{Normal Termination,,, libc, The GNU C Library
  1474. Reference Manual})).
  1475. @code{primitive-_exit} is the @code{_exit} system call
  1476. (@pxref{Termination Internals,,, libc, The GNU C Library Reference
  1477. Manual}). This terminates the program immediately, with neither
  1478. Scheme-level nor C-level cleanups.
  1479. The typical use for @code{primitive-_exit} is from a child process
  1480. created with @code{primitive-fork}. For example in a Gdk program the
  1481. child process inherits the X server connection and a C-level
  1482. @code{atexit} cleanup which will close that connection. But closing
  1483. in the child would upset the protocol in the parent, so
  1484. @code{primitive-_exit} should be used to exit without that.
  1485. @end deffn
  1486. @deffn {Scheme Procedure} execl filename arg @dots{}
  1487. @deffnx {C Function} scm_execl (filename, args)
  1488. Executes the file named by @var{filename} as a new process image.
  1489. The remaining arguments are supplied to the process; from a C program
  1490. they are accessible as the @code{argv} argument to @code{main}.
  1491. Conventionally the first @var{arg} is the same as @var{filename}.
  1492. All arguments must be strings.
  1493. If @var{arg} is missing, @var{filename} is executed with a null
  1494. argument list, which may have system-dependent side-effects.
  1495. This procedure is currently implemented using the @code{execv} system
  1496. call, but we call it @code{execl} because of its Scheme calling interface.
  1497. @end deffn
  1498. @deffn {Scheme Procedure} execlp filename arg @dots{}
  1499. @deffnx {C Function} scm_execlp (filename, args)
  1500. Similar to @code{execl}, however if
  1501. @var{filename} does not contain a slash
  1502. then the file to execute will be located by searching the
  1503. directories listed in the @code{PATH} environment variable.
  1504. This procedure is currently implemented using the @code{execvp} system
  1505. call, but we call it @code{execlp} because of its Scheme calling interface.
  1506. @end deffn
  1507. @deffn {Scheme Procedure} execle filename env arg @dots{}
  1508. @deffnx {C Function} scm_execle (filename, env, args)
  1509. Similar to @code{execl}, but the environment of the new process is
  1510. specified by @var{env}, which must be a list of strings as returned by the
  1511. @code{environ} procedure.
  1512. This procedure is currently implemented using the @code{execve} system
  1513. call, but we call it @code{execle} because of its Scheme calling interface.
  1514. @end deffn
  1515. @deffn {Scheme Procedure} primitive-fork
  1516. @deffnx {C Function} scm_fork ()
  1517. Creates a new ``child'' process by duplicating the current ``parent'' process.
  1518. In the child the return value is 0. In the parent the return value is
  1519. the integer process ID of the child.
  1520. This procedure has been renamed from @code{fork} to avoid a naming conflict
  1521. with the scsh fork.
  1522. @end deffn
  1523. @deffn {Scheme Procedure} nice incr
  1524. @deffnx {C Function} scm_nice (incr)
  1525. @cindex process priority
  1526. Increment the priority of the current process by @var{incr}. A higher
  1527. priority value means that the process runs less often.
  1528. The return value is unspecified.
  1529. @end deffn
  1530. @deffn {Scheme Procedure} setpriority which who prio
  1531. @deffnx {C Function} scm_setpriority (which, who, prio)
  1532. @vindex PRIO_PROCESS
  1533. @vindex PRIO_PGRP
  1534. @vindex PRIO_USER
  1535. Set the scheduling priority of the process, process group
  1536. or user, as indicated by @var{which} and @var{who}. @var{which}
  1537. is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
  1538. or @code{PRIO_USER}, and @var{who} is interpreted relative to
  1539. @var{which} (a process identifier for @code{PRIO_PROCESS},
  1540. process group identifier for @code{PRIO_PGRP}, and a user
  1541. identifier for @code{PRIO_USER}. A zero value of @var{who}
  1542. denotes the current process, process group, or user.
  1543. @var{prio} is a value in the range [@minus{}20,20]. The default
  1544. priority is 0; lower priorities (in numerical terms) cause more
  1545. favorable scheduling. Sets the priority of all of the specified
  1546. processes. Only the super-user may lower priorities. The return
  1547. value is not specified.
  1548. @end deffn
  1549. @deffn {Scheme Procedure} getpriority which who
  1550. @deffnx {C Function} scm_getpriority (which, who)
  1551. @vindex PRIO_PROCESS
  1552. @vindex PRIO_PGRP
  1553. @vindex PRIO_USER
  1554. Return the scheduling priority of the process, process group
  1555. or user, as indicated by @var{which} and @var{who}. @var{which}
  1556. is one of the variables @code{PRIO_PROCESS}, @code{PRIO_PGRP}
  1557. or @code{PRIO_USER}, and @var{who} should be interpreted depending on
  1558. @var{which} (a process identifier for @code{PRIO_PROCESS},
  1559. process group identifier for @code{PRIO_PGRP}, and a user
  1560. identifier for @code{PRIO_USER}). A zero value of @var{who}
  1561. denotes the current process, process group, or user. Return
  1562. the highest priority (lowest numerical value) of any of the
  1563. specified processes.
  1564. @end deffn
  1565. @cindex affinity, CPU
  1566. @deffn {Scheme Procedure} getaffinity pid
  1567. @deffnx {C Function} scm_getaffinity (pid)
  1568. Return a bitvector representing the CPU affinity mask for
  1569. process @var{pid}. Each CPU the process has affinity with
  1570. has its corresponding bit set in the returned bitvector.
  1571. The number of bits set is a good estimate of how many CPUs
  1572. Guile can use without stepping on other processes' toes.
  1573. Currently this procedure is only defined on GNU variants
  1574. (@pxref{CPU Affinity, @code{sched_getaffinity},, libc, The
  1575. GNU C Library Reference Manual}).
  1576. @end deffn
  1577. @deffn {Scheme Procedure} setaffinity pid mask
  1578. @deffnx {C Function} scm_setaffinity (pid, mask)
  1579. Install the CPU affinity mask @var{mask}, a bitvector, for
  1580. the process or thread with ID @var{pid}. The return value
  1581. is unspecified.
  1582. Currently this procedure is only defined on GNU variants
  1583. (@pxref{CPU Affinity, @code{sched_setaffinity},, libc, The
  1584. GNU C Library Reference Manual}).
  1585. @end deffn
  1586. @deffn {Scheme Procedure} total-processor-count
  1587. @deffnx {C Function} scm_total_processor_count ()
  1588. Return the total number of processors of the machine, which
  1589. is guaranteed to be at least 1. A ``processor'' here is a
  1590. thread execution unit, which can be either:
  1591. @itemize
  1592. @item an execution core in a (possibly multi-core) chip, in a
  1593. (possibly multi- chip) module, in a single computer, or
  1594. @item a thread execution unit inside a core in the case of
  1595. @dfn{hyper-threaded} CPUs.
  1596. @end itemize
  1597. Which of the two definitions is used, is unspecified.
  1598. @end deffn
  1599. @deffn {Scheme Procedure} current-processor-count
  1600. @deffnx {C Function} scm_current_processor_count ()
  1601. Like @code{total-processor-count}, but return the number of
  1602. processors available to the current process. See
  1603. @code{setaffinity} and @code{getaffinity} for more
  1604. information.
  1605. @end deffn
  1606. @node Signals
  1607. @subsection Signals
  1608. @cindex signal
  1609. The following procedures raise, handle and wait for signals.
  1610. Scheme code signal handlers are run via a system async (@pxref{System
  1611. asyncs}), so they're called in the handler's thread at the next safe
  1612. opportunity. Generally this is after any currently executing
  1613. primitive procedure finishes (which could be a long time for
  1614. primitives that wait for an external event).
  1615. @deffn {Scheme Procedure} kill pid sig
  1616. @deffnx {C Function} scm_kill (pid, sig)
  1617. Sends a signal to the specified process or group of processes.
  1618. @var{pid} specifies the processes to which the signal is sent:
  1619. @table @asis
  1620. @item @var{pid} greater than 0
  1621. The process whose identifier is @var{pid}.
  1622. @item @var{pid} equal to 0
  1623. All processes in the current process group.
  1624. @item @var{pid} less than -1
  1625. The process group whose identifier is -@var{pid}
  1626. @item @var{pid} equal to -1
  1627. If the process is privileged, all processes except for some special
  1628. system processes. Otherwise, all processes with the current effective
  1629. user ID.
  1630. @end table
  1631. @var{sig} should be specified using a variable corresponding to
  1632. the Unix symbolic name, e.g.,
  1633. @defvar SIGHUP
  1634. Hang-up signal.
  1635. @end defvar
  1636. @defvar SIGINT
  1637. Interrupt signal.
  1638. @end defvar
  1639. A full list of signals on the GNU system may be found in @ref{Standard
  1640. Signals,,,libc,The GNU C Library Reference Manual}.
  1641. @end deffn
  1642. @deffn {Scheme Procedure} raise sig
  1643. @deffnx {C Function} scm_raise (sig)
  1644. Sends a specified signal @var{sig} to the current process, where
  1645. @var{sig} is as described for the @code{kill} procedure.
  1646. @end deffn
  1647. @deffn {Scheme Procedure} sigaction signum [handler [flags [thread]]]
  1648. @deffnx {C Function} scm_sigaction (signum, handler, flags)
  1649. @deffnx {C Function} scm_sigaction_for_thread (signum, handler, flags, thread)
  1650. Install or report the signal handler for a specified signal.
  1651. @var{signum} is the signal number, which can be specified using the value
  1652. of variables such as @code{SIGINT}.
  1653. If @var{handler} is omitted, @code{sigaction} returns a pair: the
  1654. @acronym{CAR} is the current signal hander, which will be either an
  1655. integer with the value @code{SIG_DFL} (default action) or
  1656. @code{SIG_IGN} (ignore), or the Scheme procedure which handles the
  1657. signal, or @code{#f} if a non-Scheme procedure handles the signal.
  1658. The @acronym{CDR} contains the current @code{sigaction} flags for the
  1659. handler.
  1660. If @var{handler} is provided, it is installed as the new handler for
  1661. @var{signum}. @var{handler} can be a Scheme procedure taking one
  1662. argument, or the value of @code{SIG_DFL} (default action) or
  1663. @code{SIG_IGN} (ignore), or @code{#f} to restore whatever signal handler
  1664. was installed before @code{sigaction} was first used. When a scheme
  1665. procedure has been specified, that procedure will run in the given
  1666. @var{thread}. When no thread has been given, the thread that made this
  1667. call to @code{sigaction} is used.
  1668. @var{flags} is a @code{logior} (@pxref{Bitwise Operations}) of the
  1669. following (where provided by the system), or @code{0} for none.
  1670. @defvar SA_NOCLDSTOP
  1671. By default, @code{SIGCHLD} is signalled when a child process stops
  1672. (ie.@: receives @code{SIGSTOP}), and when a child process terminates.
  1673. With the @code{SA_NOCLDSTOP} flag, @code{SIGCHLD} is only signalled
  1674. for termination, not stopping.
  1675. @code{SA_NOCLDSTOP} has no effect on signals other than
  1676. @code{SIGCHLD}.
  1677. @end defvar
  1678. @defvar SA_RESTART
  1679. If a signal occurs while in a system call, deliver the signal then
  1680. restart the system call (as opposed to returning an @code{EINTR} error
  1681. from that call).
  1682. @end defvar
  1683. The return value is a pair with information about the old handler as
  1684. described above.
  1685. This interface does not provide access to the ``signal blocking''
  1686. facility. Maybe this is not needed, since the thread support may
  1687. provide solutions to the problem of consistent access to data
  1688. structures.
  1689. @end deffn
  1690. @deffn {Scheme Procedure} restore-signals
  1691. @deffnx {C Function} scm_restore_signals ()
  1692. Return all signal handlers to the values they had before any call to
  1693. @code{sigaction} was made. The return value is unspecified.
  1694. @end deffn
  1695. @deffn {Scheme Procedure} alarm i
  1696. @deffnx {C Function} scm_alarm (i)
  1697. Set a timer to raise a @code{SIGALRM} signal after the specified
  1698. number of seconds (an integer). It's advisable to install a signal
  1699. handler for
  1700. @code{SIGALRM} beforehand, since the default action is to terminate
  1701. the process.
  1702. The return value indicates the time remaining for the previous alarm,
  1703. if any. The new value replaces the previous alarm. If there was
  1704. no previous alarm, the return value is zero.
  1705. @end deffn
  1706. @deffn {Scheme Procedure} pause
  1707. @deffnx {C Function} scm_pause ()
  1708. Pause the current process (thread?) until a signal arrives whose
  1709. action is to either terminate the current process or invoke a
  1710. handler procedure. The return value is unspecified.
  1711. @end deffn
  1712. @deffn {Scheme Procedure} sleep secs
  1713. @deffnx {Scheme Procedure} usleep usecs
  1714. @deffnx {C Function} scm_sleep (secs)
  1715. @deffnx {C Function} scm_usleep (usecs)
  1716. Wait the given period @var{secs} seconds or @var{usecs} microseconds
  1717. (both integers). If a signal arrives the wait stops and the return
  1718. value is the time remaining, in seconds or microseconds respectively.
  1719. If the period elapses with no signal the return is zero.
  1720. On most systems the process scheduler is not microsecond accurate and
  1721. the actual period slept by @code{usleep} might be rounded to a system
  1722. clock tick boundary, which might be 10 milliseconds for instance.
  1723. See @code{scm_std_sleep} and @code{scm_std_usleep} for equivalents at
  1724. the C level (@pxref{Blocking}).
  1725. @end deffn
  1726. @deffn {Scheme Procedure} getitimer which_timer
  1727. @deffnx {Scheme Procedure} setitimer which_timer interval_seconds interval_microseconds periodic_seconds periodic_microseconds
  1728. @deffnx {C Function} scm_getitimer (which_timer)
  1729. @deffnx {C Function} scm_setitimer (which_timer, interval_seconds, interval_microseconds, periodic_seconds, periodic_microseconds)
  1730. Get or set the periods programmed in certain system timers. These
  1731. timers have a current interval value which counts down and on reaching
  1732. zero raises a signal. An optional periodic value can be set to
  1733. restart from there each time, for periodic operation.
  1734. @var{which_timer} is one of the following values
  1735. @defvar ITIMER_REAL
  1736. A real-time timer, counting down elapsed real time. At zero it raises
  1737. @code{SIGALRM}. This is like @code{alarm} above, but with a higher
  1738. resolution period.
  1739. @end defvar
  1740. @defvar ITIMER_VIRTUAL
  1741. A virtual-time timer, counting down while the current process is
  1742. actually using CPU. At zero it raises @code{SIGVTALRM}.
  1743. @end defvar
  1744. @defvar ITIMER_PROF
  1745. A profiling timer, counting down while the process is running (like
  1746. @code{ITIMER_VIRTUAL}) and also while system calls are running on the
  1747. process's behalf. At zero it raises a @code{SIGPROF}.
  1748. This timer is intended for profiling where a program is spending its
  1749. time (by looking where it is when the timer goes off).
  1750. @end defvar
  1751. @code{getitimer} returns the current timer value and its programmed
  1752. restart value, as a list containing two pairs. Each pair is a time in
  1753. seconds and microseconds: @code{((@var{interval_secs}
  1754. . @var{interval_usecs}) (@var{periodic_secs}
  1755. . @var{periodic_usecs}))}.
  1756. @code{setitimer} sets the timer values similarly, in seconds and
  1757. microseconds (which must be integers). The periodic value can be zero
  1758. to have the timer run down just once. The return value is the timer's
  1759. previous setting, in the same form as @code{getitimer} returns.
  1760. @example
  1761. (setitimer ITIMER_REAL
  1762. 5 500000 ;; first SIGALRM in 5.5 seconds time
  1763. 2 0) ;; then repeat every 2 seconds
  1764. @end example
  1765. Although the timers are programmed in microseconds, the actual
  1766. accuracy might not be that high.
  1767. @end deffn
  1768. @node Terminals and Ptys
  1769. @subsection Terminals and Ptys
  1770. @deffn {Scheme Procedure} isatty? port
  1771. @deffnx {C Function} scm_isatty_p (port)
  1772. @cindex terminal
  1773. Return @code{#t} if @var{port} is using a serial non--file
  1774. device, otherwise @code{#f}.
  1775. @end deffn
  1776. @deffn {Scheme Procedure} ttyname port
  1777. @deffnx {C Function} scm_ttyname (port)
  1778. @cindex terminal
  1779. Return a string with the name of the serial terminal device
  1780. underlying @var{port}.
  1781. @end deffn
  1782. @deffn {Scheme Procedure} ctermid
  1783. @deffnx {C Function} scm_ctermid ()
  1784. @cindex terminal
  1785. Return a string containing the file name of the controlling
  1786. terminal for the current process.
  1787. @end deffn
  1788. @deffn {Scheme Procedure} tcgetpgrp port
  1789. @deffnx {C Function} scm_tcgetpgrp (port)
  1790. @cindex process group
  1791. Return the process group ID of the foreground process group
  1792. associated with the terminal open on the file descriptor
  1793. underlying @var{port}.
  1794. If there is no foreground process group, the return value is a
  1795. number greater than 1 that does not match the process group ID
  1796. of any existing process group. This can happen if all of the
  1797. processes in the job that was formerly the foreground job have
  1798. terminated, and no other job has yet been moved into the
  1799. foreground.
  1800. @end deffn
  1801. @deffn {Scheme Procedure} tcsetpgrp port pgid
  1802. @deffnx {C Function} scm_tcsetpgrp (port, pgid)
  1803. @cindex process group
  1804. Set the foreground process group ID for the terminal used by the file
  1805. descriptor underlying @var{port} to the integer @var{pgid}.
  1806. The calling process
  1807. must be a member of the same session as @var{pgid} and must have the same
  1808. controlling terminal. The return value is unspecified.
  1809. @end deffn
  1810. @node Pipes
  1811. @subsection Pipes
  1812. @cindex pipe
  1813. The following procedures are similar to the @code{popen} and
  1814. @code{pclose} system routines. The code is in a separate ``popen''
  1815. module:
  1816. @lisp
  1817. (use-modules (ice-9 popen))
  1818. @end lisp
  1819. @findex popen
  1820. @deffn {Scheme Procedure} open-pipe command mode
  1821. @deffnx {Scheme Procedure} open-pipe* mode prog [args...]
  1822. Execute a command in a subprocess, with a pipe to it or from it, or
  1823. with pipes in both directions.
  1824. @code{open-pipe} runs the shell @var{command} using @samp{/bin/sh -c}.
  1825. @code{open-pipe*} executes @var{prog} directly, with the optional
  1826. @var{args} arguments (all strings).
  1827. @var{mode} should be one of the following values. @code{OPEN_READ} is
  1828. an input pipe, ie.@: to read from the subprocess. @code{OPEN_WRITE}
  1829. is an output pipe, ie.@: to write to it.
  1830. @defvar OPEN_READ
  1831. @defvarx OPEN_WRITE
  1832. @defvarx OPEN_BOTH
  1833. @end defvar
  1834. For an input pipe, the child's standard output is the pipe and
  1835. standard input is inherited from @code{current-input-port}. For an
  1836. output pipe, the child's standard input is the pipe and standard
  1837. output is inherited from @code{current-output-port}. In all cases
  1838. cases the child's standard error is inherited from
  1839. @code{current-error-port} (@pxref{Default Ports}).
  1840. If those @code{current-X-ports} are not files of some kind, and hence
  1841. don't have file descriptors for the child, then @file{/dev/null} is
  1842. used instead.
  1843. Care should be taken with @code{OPEN_BOTH}, a deadlock will occur if
  1844. both parent and child are writing, and waiting until the write
  1845. completes before doing any reading. Each direction has
  1846. @code{PIPE_BUF} bytes of buffering (@pxref{Ports and File
  1847. Descriptors}), which will be enough for small writes, but not for say
  1848. putting a big file through a filter.
  1849. @end deffn
  1850. @deffn {Scheme Procedure} open-input-pipe command
  1851. Equivalent to @code{open-pipe} with mode @code{OPEN_READ}.
  1852. @lisp
  1853. (let* ((port (open-input-pipe "date --utc"))
  1854. (str (read-line port)))
  1855. (close-pipe port)
  1856. str)
  1857. @result{} "Mon Mar 11 20:10:44 UTC 2002"
  1858. @end lisp
  1859. @end deffn
  1860. @deffn {Scheme Procedure} open-output-pipe command
  1861. Equivalent to @code{open-pipe} with mode @code{OPEN_WRITE}.
  1862. @lisp
  1863. (let ((port (open-output-pipe "lpr")))
  1864. (display "Something for the line printer.\n" port)
  1865. (if (not (eqv? 0 (status:exit-val (close-pipe port))))
  1866. (error "Cannot print")))
  1867. @end lisp
  1868. @end deffn
  1869. @deffn {Scheme Procedure} open-input-output-pipe command
  1870. Equivalent to @code{open-pipe} with mode @code{OPEN_BOTH}.
  1871. @end deffn
  1872. @findex pclose
  1873. @deffn {Scheme Procedure} close-pipe port
  1874. Close a pipe created by @code{open-pipe}, wait for the process to
  1875. terminate, and return the wait status code. The status is as per
  1876. @code{waitpid} and can be decoded with @code{status:exit-val} etc
  1877. (@pxref{Processes})
  1878. @end deffn
  1879. @sp 1
  1880. @code{waitpid WAIT_ANY} should not be used when pipes are open, since
  1881. it can reap a pipe's child process, causing an error from a subsequent
  1882. @code{close-pipe}.
  1883. @code{close-port} (@pxref{Closing}) can close a pipe, but it doesn't
  1884. reap the child process.
  1885. The garbage collector will close a pipe no longer in use, and reap the
  1886. child process with @code{waitpid}. If the child hasn't yet terminated
  1887. the garbage collector doesn't block, but instead checks again in the
  1888. next GC.
  1889. Many systems have per-user and system-wide limits on the number of
  1890. processes, and a system-wide limit on the number of pipes, so pipes
  1891. should be closed explicitly when no longer needed, rather than letting
  1892. the garbage collector pick them up at some later time.
  1893. @node Networking
  1894. @subsection Networking
  1895. @cindex network
  1896. @menu
  1897. * Network Address Conversion::
  1898. * Network Databases::
  1899. * Network Socket Address::
  1900. * Network Sockets and Communication::
  1901. * Internet Socket Examples::
  1902. @end menu
  1903. @node Network Address Conversion
  1904. @subsubsection Network Address Conversion
  1905. @cindex network address
  1906. This section describes procedures which convert internet addresses
  1907. between numeric and string formats.
  1908. @subsubheading IPv4 Address Conversion
  1909. @cindex IPv4
  1910. An IPv4 Internet address is a 4-byte value, represented in Guile as an
  1911. integer in host byte order, so that say ``0.0.0.1'' is 1, or
  1912. ``1.0.0.0'' is 16777216.
  1913. Some underlying C functions use network byte order for addresses,
  1914. Guile converts as necessary so that at the Scheme level its host byte
  1915. order everywhere.
  1916. @defvar INADDR_ANY
  1917. For a server, this can be used with @code{bind} (@pxref{Network
  1918. Sockets and Communication}) to allow connections from any interface on
  1919. the machine.
  1920. @end defvar
  1921. @defvar INADDR_BROADCAST
  1922. The broadcast address on the local network.
  1923. @end defvar
  1924. @defvar INADDR_LOOPBACK
  1925. The address of the local host using the loopback device, ie.@:
  1926. @samp{127.0.0.1}.
  1927. @end defvar
  1928. @c INADDR_NONE is defined in the code, but serves no purpose.
  1929. @c inet_addr() returns it as an error indication, but that function
  1930. @c isn't provided, for the good reason that inet_aton() does the same
  1931. @c job and gives an unambiguous error indication. (INADDR_NONE is a
  1932. @c valid 4-byte value, in glibc it's the same as INADDR_BROADCAST.)
  1933. @c
  1934. @c @defvar INADDR_NONE
  1935. @c No address.
  1936. @c @end defvar
  1937. @deffn {Scheme Procedure} inet-aton address
  1938. @deffnx {C Function} scm_inet_aton (address)
  1939. This function is deprecated in favor of @code{inet-pton}.
  1940. Convert an IPv4 Internet address from printable string
  1941. (dotted decimal notation) to an integer. E.g.,
  1942. @lisp
  1943. (inet-aton "127.0.0.1") @result{} 2130706433
  1944. @end lisp
  1945. @end deffn
  1946. @deffn {Scheme Procedure} inet-ntoa inetid
  1947. @deffnx {C Function} scm_inet_ntoa (inetid)
  1948. This function is deprecated in favor of @code{inet-ntop}.
  1949. Convert an IPv4 Internet address to a printable
  1950. (dotted decimal notation) string. E.g.,
  1951. @lisp
  1952. (inet-ntoa 2130706433) @result{} "127.0.0.1"
  1953. @end lisp
  1954. @end deffn
  1955. @deffn {Scheme Procedure} inet-netof address
  1956. @deffnx {C Function} scm_inet_netof (address)
  1957. Return the network number part of the given IPv4
  1958. Internet address. E.g.,
  1959. @lisp
  1960. (inet-netof 2130706433) @result{} 127
  1961. @end lisp
  1962. @end deffn
  1963. @deffn {Scheme Procedure} inet-lnaof address
  1964. @deffnx {C Function} scm_lnaof (address)
  1965. Return the local-address-with-network part of the given
  1966. IPv4 Internet address, using the obsolete class A/B/C system.
  1967. E.g.,
  1968. @lisp
  1969. (inet-lnaof 2130706433) @result{} 1
  1970. @end lisp
  1971. @end deffn
  1972. @deffn {Scheme Procedure} inet-makeaddr net lna
  1973. @deffnx {C Function} scm_inet_makeaddr (net, lna)
  1974. Make an IPv4 Internet address by combining the network number
  1975. @var{net} with the local-address-within-network number
  1976. @var{lna}. E.g.,
  1977. @lisp
  1978. (inet-makeaddr 127 1) @result{} 2130706433
  1979. @end lisp
  1980. @end deffn
  1981. @subsubheading IPv6 Address Conversion
  1982. @cindex IPv6
  1983. An IPv6 Internet address is a 16-byte value, represented in Guile as
  1984. an integer in host byte order, so that say ``::1'' is 1.
  1985. @deffn {Scheme Procedure} inet-ntop family address
  1986. @deffnx {C Function} scm_inet_ntop (family, address)
  1987. Convert a network address from an integer to a printable string.
  1988. @var{family} can be @code{AF_INET} or @code{AF_INET6}. E.g.,
  1989. @lisp
  1990. (inet-ntop AF_INET 2130706433) @result{} "127.0.0.1"
  1991. (inet-ntop AF_INET6 (- (expt 2 128) 1))
  1992. @result{} "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"
  1993. @end lisp
  1994. @end deffn
  1995. @deffn {Scheme Procedure} inet-pton family address
  1996. @deffnx {C Function} scm_inet_pton (family, address)
  1997. Convert a string containing a printable network address to an integer
  1998. address. @var{family} can be @code{AF_INET} or @code{AF_INET6}.
  1999. E.g.,
  2000. @lisp
  2001. (inet-pton AF_INET "127.0.0.1") @result{} 2130706433
  2002. (inet-pton AF_INET6 "::1") @result{} 1
  2003. @end lisp
  2004. @end deffn
  2005. @node Network Databases
  2006. @subsubsection Network Databases
  2007. @cindex network database
  2008. This section describes procedures which query various network databases.
  2009. Care should be taken when using the database routines since they are not
  2010. reentrant.
  2011. @subsubheading @code{getaddrinfo}
  2012. @cindex @code{addrinfo} object type
  2013. @cindex host name lookup
  2014. @cindex service name lookup
  2015. The @code{getaddrinfo} procedure maps host and service names to socket addresses
  2016. and associated information in a protocol-independent way.
  2017. @deffn {Scheme Procedure} getaddrinfo name service [hint_flags [hint_family [hint_socktype [hint_protocol]]]]
  2018. @deffnx {C Function} scm_getaddrinfo (name, service, hint_flags, hint_family, hint_socktype, hint_protocol)
  2019. Return a list of @code{addrinfo} structures containing
  2020. a socket address and associated information for host @var{name}
  2021. and/or @var{service} to be used in creating a socket with
  2022. which to address the specified service.
  2023. @example
  2024. (let* ((ai (car (getaddrinfo "www.gnu.org" "http")))
  2025. (s (socket (addrinfo:fam ai) (addrinfo:socktype ai)
  2026. (addrinfo:protocol ai))))
  2027. (connect s (addrinfo:addr ai))
  2028. s)
  2029. @end example
  2030. When @var{service} is omitted or is @code{#f}, return
  2031. network-level addresses for @var{name}. When @var{name}
  2032. is @code{#f} @var{service} must be provided and service
  2033. locations local to the caller are returned.
  2034. Additional hints can be provided. When specified,
  2035. @var{hint_flags} should be a bitwise-or of zero or more
  2036. constants among the following:
  2037. @table @code
  2038. @item AI_PASSIVE
  2039. Socket address is intended for @code{bind}.
  2040. @item AI_CANONNAME
  2041. Request for canonical host name, available via
  2042. @code{addrinfo:canonname}. This makes sense mainly when
  2043. DNS lookups are involved.
  2044. @item AI_NUMERICHOST
  2045. Specifies that @var{name} is a numeric host address string
  2046. (e.g., @code{"127.0.0.1"}), meaning that name resolution
  2047. will not be used.
  2048. @item AI_NUMERICSERV
  2049. Likewise, specifies that @var{service} is a numeric port
  2050. string (e.g., @code{"80"}).
  2051. @item AI_ADDRCONFIG
  2052. Return only addresses configured on the local system It is
  2053. highly recommended to provide this flag when the returned
  2054. socket addresses are to be used to make connections;
  2055. otherwise, some of the returned addresses could be unreachable
  2056. or use a protocol that is not supported.
  2057. @item AI_V4MAPPED
  2058. When looking up IPv6 addresses, return mapped IPv4 addresses if
  2059. there is no IPv6 address available at all.
  2060. @item AI_ALL
  2061. If this flag is set along with @code{AI_V4MAPPED} when looking up IPv6
  2062. addresses, return all IPv6 addresses as well as all IPv4 addresses, the latter
  2063. mapped to IPv6 format.
  2064. @end table
  2065. When given, @var{hint_family} should specify the requested
  2066. address family, e.g., @code{AF_INET6}. Similarly,
  2067. @var{hint_socktype} should specify the requested socket type
  2068. (e.g., @code{SOCK_DGRAM}), and @var{hint_protocol} should
  2069. specify the requested protocol (its value is interpreted
  2070. as in calls to @code{socket}).
  2071. On error, an exception with key @code{getaddrinfo-error} is
  2072. thrown, with an error code (an integer) as its argument:
  2073. @example
  2074. (catch 'getaddrinfo-error
  2075. (lambda ()
  2076. (getaddrinfo "www.gnu.org" "gopher"))
  2077. (lambda (key errcode)
  2078. (cond ((= errcode EAI_SERVICE)
  2079. (display "doesn't know about Gopher!\n"))
  2080. ((= errcode EAI_NONAME)
  2081. (display "www.gnu.org not found\\n"))
  2082. (else
  2083. (format #t "something wrong: ~a\n"
  2084. (gai-strerror errcode))))))
  2085. @end example
  2086. Error codes are:
  2087. @table @code
  2088. @item EAI_AGAIN
  2089. The name or service could not be resolved at this time. Future
  2090. attempts may succeed.
  2091. @item EAI_BADFLAGS
  2092. @var{hint_flags} contains an invalid value.
  2093. @item EAI_FAIL
  2094. A non-recoverable error occurred when attempting to
  2095. resolve the name.
  2096. @item EAI_FAMILY
  2097. @var{hint_family} was not recognized.
  2098. @item EAI_NONAME
  2099. Either @var{name} does not resolve for the supplied parameters,
  2100. or neither @var{name} nor @var{service} were supplied.
  2101. @item EAI_NODATA
  2102. This non-POSIX error code can be returned on some systems (GNU
  2103. and Darwin, at least), for example when @var{name} is known
  2104. but requests that were made turned out no data. Error handling
  2105. code should be prepared to handle it when it is defined.
  2106. @item EAI_SERVICE
  2107. @var{service} was not recognized for the specified socket type.
  2108. @item EAI_SOCKTYPE
  2109. @var{hint_socktype} was not recognized.
  2110. @item EAI_SYSTEM
  2111. A system error occurred; the error code can be found in
  2112. @code{errno}.
  2113. @end table
  2114. Users are encouraged to read the
  2115. @url{http://www.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html,
  2116. "POSIX specification} for more details.
  2117. @end deffn
  2118. The following procedures take an @code{addrinfo} object as returned by
  2119. @code{getaddrinfo}:
  2120. @deffn {Scheme Procedure} addrinfo:flags ai
  2121. Return flags for @var{ai} as a bitwise or of @code{AI_} values (see above).
  2122. @end deffn
  2123. @deffn {Scheme Procedure} addrinfo:fam ai
  2124. Return the address family of @var{ai} (a @code{AF_} value).
  2125. @end deffn
  2126. @deffn {Scheme Procedure} addrinfo:socktype ai
  2127. Return the socket type for @var{ai} (a @code{SOCK_} value).
  2128. @end deffn
  2129. @deffn {Scheme Procedure} addrinfo:protocol ai
  2130. Return the protocol of @var{ai}.
  2131. @end deffn
  2132. @deffn {Scheme Procedure} addrinfo:addr ai
  2133. Return the socket address associated with @var{ai} as a @code{sockaddr}
  2134. object (@pxref{Network Socket Address}).
  2135. @end deffn
  2136. @deffn {Scheme Procedure} addrinfo:canonname ai
  2137. Return a string for the canonical name associated with @var{ai} if
  2138. the @code{AI_CANONNAME} flag was supplied.
  2139. @end deffn
  2140. @subsubheading The Host Database
  2141. @cindex @file{/etc/hosts}
  2142. @cindex network database
  2143. A @dfn{host object} is a structure that represents what is known about a
  2144. network host, and is the usual way of representing a system's network
  2145. identity inside software.
  2146. The following functions accept a host object and return a selected
  2147. component:
  2148. @deffn {Scheme Procedure} hostent:name host
  2149. The ``official'' hostname for @var{host}.
  2150. @end deffn
  2151. @deffn {Scheme Procedure} hostent:aliases host
  2152. A list of aliases for @var{host}.
  2153. @end deffn
  2154. @deffn {Scheme Procedure} hostent:addrtype host
  2155. The host address type, one of the @code{AF} constants, such as
  2156. @code{AF_INET} or @code{AF_INET6}.
  2157. @end deffn
  2158. @deffn {Scheme Procedure} hostent:length host
  2159. The length of each address for @var{host}, in bytes.
  2160. @end deffn
  2161. @deffn {Scheme Procedure} hostent:addr-list host
  2162. The list of network addresses associated with @var{host}. For
  2163. @code{AF_INET} these are integer IPv4 address (@pxref{Network Address
  2164. Conversion}).
  2165. @end deffn
  2166. The following procedures can be used to search the host database. However,
  2167. @code{getaddrinfo} should be preferred over them since it's more generic and
  2168. thread-safe.
  2169. @deffn {Scheme Procedure} gethost [host]
  2170. @deffnx {Scheme Procedure} gethostbyname hostname
  2171. @deffnx {Scheme Procedure} gethostbyaddr address
  2172. @deffnx {C Function} scm_gethost (host)
  2173. Look up a host by name or address, returning a host object. The
  2174. @code{gethost} procedure will accept either a string name or an integer
  2175. address; if given no arguments, it behaves like @code{gethostent} (see
  2176. below). If a name or address is supplied but the address can not be
  2177. found, an error will be thrown to one of the keys:
  2178. @code{host-not-found}, @code{try-again}, @code{no-recovery} or
  2179. @code{no-data}, corresponding to the equivalent @code{h_error} values.
  2180. Unusual conditions may result in errors thrown to the
  2181. @code{system-error} or @code{misc_error} keys.
  2182. @lisp
  2183. (gethost "www.gnu.org")
  2184. @result{} #("www.gnu.org" () 2 4 (3353880842))
  2185. (gethostbyname "www.emacs.org")
  2186. @result{} #("emacs.org" ("www.emacs.org") 2 4 (1073448978))
  2187. @end lisp
  2188. @end deffn
  2189. The following procedures may be used to step through the host
  2190. database from beginning to end.
  2191. @deffn {Scheme Procedure} sethostent [stayopen]
  2192. Initialize an internal stream from which host objects may be read. This
  2193. procedure must be called before any calls to @code{gethostent}, and may
  2194. also be called afterward to reset the host entry stream. If
  2195. @var{stayopen} is supplied and is not @code{#f}, the database is not
  2196. closed by subsequent @code{gethostbyname} or @code{gethostbyaddr} calls,
  2197. possibly giving an efficiency gain.
  2198. @end deffn
  2199. @deffn {Scheme Procedure} gethostent
  2200. Return the next host object from the host database, or @code{#f} if
  2201. there are no more hosts to be found (or an error has been encountered).
  2202. This procedure may not be used before @code{sethostent} has been called.
  2203. @end deffn
  2204. @deffn {Scheme Procedure} endhostent
  2205. Close the stream used by @code{gethostent}. The return value is unspecified.
  2206. @end deffn
  2207. @deffn {Scheme Procedure} sethost [stayopen]
  2208. @deffnx {C Function} scm_sethost (stayopen)
  2209. If @var{stayopen} is omitted, this is equivalent to @code{endhostent}.
  2210. Otherwise it is equivalent to @code{sethostent stayopen}.
  2211. @end deffn
  2212. @subsubheading The Network Database
  2213. @cindex network database
  2214. The following functions accept an object representing a network
  2215. and return a selected component:
  2216. @deffn {Scheme Procedure} netent:name net
  2217. The ``official'' network name.
  2218. @end deffn
  2219. @deffn {Scheme Procedure} netent:aliases net
  2220. A list of aliases for the network.
  2221. @end deffn
  2222. @deffn {Scheme Procedure} netent:addrtype net
  2223. The type of the network number. Currently, this returns only
  2224. @code{AF_INET}.
  2225. @end deffn
  2226. @deffn {Scheme Procedure} netent:net net
  2227. The network number.
  2228. @end deffn
  2229. The following procedures are used to search the network database:
  2230. @deffn {Scheme Procedure} getnet [net]
  2231. @deffnx {Scheme Procedure} getnetbyname net-name
  2232. @deffnx {Scheme Procedure} getnetbyaddr net-number
  2233. @deffnx {C Function} scm_getnet (net)
  2234. Look up a network by name or net number in the network database. The
  2235. @var{net-name} argument must be a string, and the @var{net-number}
  2236. argument must be an integer. @code{getnet} will accept either type of
  2237. argument, behaving like @code{getnetent} (see below) if no arguments are
  2238. given.
  2239. @end deffn
  2240. The following procedures may be used to step through the network
  2241. database from beginning to end.
  2242. @deffn {Scheme Procedure} setnetent [stayopen]
  2243. Initialize an internal stream from which network objects may be read. This
  2244. procedure must be called before any calls to @code{getnetent}, and may
  2245. also be called afterward to reset the net entry stream. If
  2246. @var{stayopen} is supplied and is not @code{#f}, the database is not
  2247. closed by subsequent @code{getnetbyname} or @code{getnetbyaddr} calls,
  2248. possibly giving an efficiency gain.
  2249. @end deffn
  2250. @deffn {Scheme Procedure} getnetent
  2251. Return the next entry from the network database.
  2252. @end deffn
  2253. @deffn {Scheme Procedure} endnetent
  2254. Close the stream used by @code{getnetent}. The return value is unspecified.
  2255. @end deffn
  2256. @deffn {Scheme Procedure} setnet [stayopen]
  2257. @deffnx {C Function} scm_setnet (stayopen)
  2258. If @var{stayopen} is omitted, this is equivalent to @code{endnetent}.
  2259. Otherwise it is equivalent to @code{setnetent stayopen}.
  2260. @end deffn
  2261. @subsubheading The Protocol Database
  2262. @cindex @file{/etc/protocols}
  2263. @cindex protocols
  2264. @cindex network protocols
  2265. The following functions accept an object representing a protocol
  2266. and return a selected component:
  2267. @deffn {Scheme Procedure} protoent:name protocol
  2268. The ``official'' protocol name.
  2269. @end deffn
  2270. @deffn {Scheme Procedure} protoent:aliases protocol
  2271. A list of aliases for the protocol.
  2272. @end deffn
  2273. @deffn {Scheme Procedure} protoent:proto protocol
  2274. The protocol number.
  2275. @end deffn
  2276. The following procedures are used to search the protocol database:
  2277. @deffn {Scheme Procedure} getproto [protocol]
  2278. @deffnx {Scheme Procedure} getprotobyname name
  2279. @deffnx {Scheme Procedure} getprotobynumber number
  2280. @deffnx {C Function} scm_getproto (protocol)
  2281. Look up a network protocol by name or by number. @code{getprotobyname}
  2282. takes a string argument, and @code{getprotobynumber} takes an integer
  2283. argument. @code{getproto} will accept either type, behaving like
  2284. @code{getprotoent} (see below) if no arguments are supplied.
  2285. @end deffn
  2286. The following procedures may be used to step through the protocol
  2287. database from beginning to end.
  2288. @deffn {Scheme Procedure} setprotoent [stayopen]
  2289. Initialize an internal stream from which protocol objects may be read. This
  2290. procedure must be called before any calls to @code{getprotoent}, and may
  2291. also be called afterward to reset the protocol entry stream. If
  2292. @var{stayopen} is supplied and is not @code{#f}, the database is not
  2293. closed by subsequent @code{getprotobyname} or @code{getprotobynumber} calls,
  2294. possibly giving an efficiency gain.
  2295. @end deffn
  2296. @deffn {Scheme Procedure} getprotoent
  2297. Return the next entry from the protocol database.
  2298. @end deffn
  2299. @deffn {Scheme Procedure} endprotoent
  2300. Close the stream used by @code{getprotoent}. The return value is unspecified.
  2301. @end deffn
  2302. @deffn {Scheme Procedure} setproto [stayopen]
  2303. @deffnx {C Function} scm_setproto (stayopen)
  2304. If @var{stayopen} is omitted, this is equivalent to @code{endprotoent}.
  2305. Otherwise it is equivalent to @code{setprotoent stayopen}.
  2306. @end deffn
  2307. @subsubheading The Service Database
  2308. @cindex @file{/etc/services}
  2309. @cindex services
  2310. @cindex network services
  2311. The following functions accept an object representing a service
  2312. and return a selected component:
  2313. @deffn {Scheme Procedure} servent:name serv
  2314. The ``official'' name of the network service.
  2315. @end deffn
  2316. @deffn {Scheme Procedure} servent:aliases serv
  2317. A list of aliases for the network service.
  2318. @end deffn
  2319. @deffn {Scheme Procedure} servent:port serv
  2320. The Internet port used by the service.
  2321. @end deffn
  2322. @deffn {Scheme Procedure} servent:proto serv
  2323. The protocol used by the service. A service may be listed many times
  2324. in the database under different protocol names.
  2325. @end deffn
  2326. The following procedures are used to search the service database:
  2327. @deffn {Scheme Procedure} getserv [name [protocol]]
  2328. @deffnx {Scheme Procedure} getservbyname name protocol
  2329. @deffnx {Scheme Procedure} getservbyport port protocol
  2330. @deffnx {C Function} scm_getserv (name, protocol)
  2331. Look up a network service by name or by service number, and return a
  2332. network service object. The @var{protocol} argument specifies the name
  2333. of the desired protocol; if the protocol found in the network service
  2334. database does not match this name, a system error is signalled.
  2335. The @code{getserv} procedure will take either a service name or number
  2336. as its first argument; if given no arguments, it behaves like
  2337. @code{getservent} (see below).
  2338. @lisp
  2339. (getserv "imap" "tcp")
  2340. @result{} #("imap2" ("imap") 143 "tcp")
  2341. (getservbyport 88 "udp")
  2342. @result{} #("kerberos" ("kerberos5" "krb5") 88 "udp")
  2343. @end lisp
  2344. @end deffn
  2345. The following procedures may be used to step through the service
  2346. database from beginning to end.
  2347. @deffn {Scheme Procedure} setservent [stayopen]
  2348. Initialize an internal stream from which service objects may be read. This
  2349. procedure must be called before any calls to @code{getservent}, and may
  2350. also be called afterward to reset the service entry stream. If
  2351. @var{stayopen} is supplied and is not @code{#f}, the database is not
  2352. closed by subsequent @code{getservbyname} or @code{getservbyport} calls,
  2353. possibly giving an efficiency gain.
  2354. @end deffn
  2355. @deffn {Scheme Procedure} getservent
  2356. Return the next entry from the services database.
  2357. @end deffn
  2358. @deffn {Scheme Procedure} endservent
  2359. Close the stream used by @code{getservent}. The return value is unspecified.
  2360. @end deffn
  2361. @deffn {Scheme Procedure} setserv [stayopen]
  2362. @deffnx {C Function} scm_setserv (stayopen)
  2363. If @var{stayopen} is omitted, this is equivalent to @code{endservent}.
  2364. Otherwise it is equivalent to @code{setservent stayopen}.
  2365. @end deffn
  2366. @node Network Socket Address
  2367. @subsubsection Network Socket Address
  2368. @cindex socket address
  2369. @cindex network socket address
  2370. @tpindex Socket address
  2371. A @dfn{socket address} object identifies a socket endpoint for
  2372. communication. In the case of @code{AF_INET} for instance, the socket
  2373. address object comprises the host address (or interface on the host)
  2374. and a port number which specifies a particular open socket in a
  2375. running client or server process. A socket address object can be
  2376. created with,
  2377. @deffn {Scheme Procedure} make-socket-address AF_INET ipv4addr port
  2378. @deffnx {Scheme Procedure} make-socket-address AF_INET6 ipv6addr port [flowinfo [scopeid]]
  2379. @deffnx {Scheme Procedure} make-socket-address AF_UNIX path
  2380. @deffnx {C Function} scm_make_socket_address (family, address, arglist)
  2381. Return a new socket address object. The first argument is the address
  2382. family, one of the @code{AF} constants, then the arguments vary
  2383. according to the family.
  2384. For @code{AF_INET} the arguments are an IPv4 network address number
  2385. (@pxref{Network Address Conversion}), and a port number.
  2386. For @code{AF_INET6} the arguments are an IPv6 network address number
  2387. and a port number. Optional @var{flowinfo} and @var{scopeid}
  2388. arguments may be given (both integers, default 0).
  2389. For @code{AF_UNIX} the argument is a filename (a string).
  2390. The C function @code{scm_make_socket_address} takes the @var{family}
  2391. and @var{address} arguments directly, then @var{arglist} is a list of
  2392. further arguments, being the port for IPv4, port and optional flowinfo
  2393. and scopeid for IPv6, or the empty list @code{SCM_EOL} for Unix
  2394. domain.
  2395. @end deffn
  2396. @noindent
  2397. The following functions access the fields of a socket address object,
  2398. @deffn {Scheme Procedure} sockaddr:fam sa
  2399. Return the address family from socket address object @var{sa}. This
  2400. is one of the @code{AF} constants (e.g.@: @code{AF_INET}).
  2401. @end deffn
  2402. @deffn {Scheme Procedure} sockaddr:path sa
  2403. For an @code{AF_UNIX} socket address object @var{sa}, return the
  2404. filename.
  2405. @end deffn
  2406. @deffn {Scheme Procedure} sockaddr:addr sa
  2407. For an @code{AF_INET} or @code{AF_INET6} socket address object
  2408. @var{sa}, return the network address number.
  2409. @end deffn
  2410. @deffn {Scheme Procedure} sockaddr:port sa
  2411. For an @code{AF_INET} or @code{AF_INET6} socket address object
  2412. @var{sa}, return the port number.
  2413. @end deffn
  2414. @deffn {Scheme Procedure} sockaddr:flowinfo sa
  2415. For an @code{AF_INET6} socket address object @var{sa}, return the
  2416. flowinfo value.
  2417. @end deffn
  2418. @deffn {Scheme Procedure} sockaddr:scopeid sa
  2419. For an @code{AF_INET6} socket address object @var{sa}, return the
  2420. scope ID value.
  2421. @end deffn
  2422. @tpindex @code{struct sockaddr}
  2423. @tpindex @code{sockaddr}
  2424. The functions below convert to and from the C @code{struct sockaddr}
  2425. (@pxref{Address Formats,,, libc, The GNU C Library Reference Manual}).
  2426. That structure is a generic type, an application can cast to or from
  2427. @code{struct sockaddr_in}, @code{struct sockaddr_in6} or @code{struct
  2428. sockaddr_un} according to the address family.
  2429. In a @code{struct sockaddr} taken or returned, the byte ordering in
  2430. the fields follows the C conventions (@pxref{Byte Order,, Byte Order
  2431. Conversion, libc, The GNU C Library Reference Manual}). This means
  2432. network byte order for @code{AF_INET} host address
  2433. (@code{sin_addr.s_addr}) and port number (@code{sin_port}), and
  2434. @code{AF_INET6} port number (@code{sin6_port}). But at the Scheme
  2435. level these values are taken or returned in host byte order, so the
  2436. port is an ordinary integer, and the host address likewise is an
  2437. ordinary integer (as described in @ref{Network Address Conversion}).
  2438. @deftypefn {C Function} {struct sockaddr *} scm_c_make_socket_address (SCM family, SCM address, SCM args, size_t *outsize)
  2439. Return a newly-@code{malloc}ed @code{struct sockaddr} created from
  2440. arguments like those taken by @code{scm_make_socket_address} above.
  2441. The size (in bytes) of the @code{struct sockaddr} return is stored
  2442. into @code{*@var{outsize}}. An application must call @code{free} to
  2443. release the returned structure when no longer required.
  2444. @end deftypefn
  2445. @deftypefn {C Function} SCM scm_from_sockaddr (const struct sockaddr *address, unsigned address_size)
  2446. Return a Scheme socket address object from the C @var{address}
  2447. structure. @var{address_size} is the size in bytes of @var{address}.
  2448. @end deftypefn
  2449. @deftypefn {C Function} {struct sockaddr *} scm_to_sockaddr (SCM address, size_t *address_size)
  2450. Return a newly-@code{malloc}ed @code{struct sockaddr} from a Scheme
  2451. level socket address object.
  2452. The size (in bytes) of the @code{struct sockaddr} return is stored
  2453. into @code{*@var{outsize}}. An application must call @code{free} to
  2454. release the returned structure when no longer required.
  2455. @end deftypefn
  2456. @node Network Sockets and Communication
  2457. @subsubsection Network Sockets and Communication
  2458. @cindex socket
  2459. @cindex network socket
  2460. Socket ports can be created using @code{socket} and @code{socketpair}.
  2461. The ports are initially unbuffered, to make reading and writing to the
  2462. same port more reliable. A buffer can be added to the port using
  2463. @code{setvbuf}; see @ref{Ports and File Descriptors}.
  2464. Most systems have limits on how many files and sockets can be open, so
  2465. it's strongly recommended that socket ports be closed explicitly when
  2466. no longer required (@pxref{Ports}).
  2467. Some of the underlying C functions take values in network byte order,
  2468. but the convention in Guile is that at the Scheme level everything is
  2469. ordinary host byte order and conversions are made automatically where
  2470. necessary.
  2471. @deffn {Scheme Procedure} socket family style proto
  2472. @deffnx {C Function} scm_socket (family, style, proto)
  2473. Return a new socket port of the type specified by @var{family},
  2474. @var{style} and @var{proto}. All three parameters are integers. The
  2475. possible values for @var{family} are as follows, where supported by
  2476. the system,
  2477. @defvar PF_UNIX
  2478. @defvarx PF_INET
  2479. @defvarx PF_INET6
  2480. @end defvar
  2481. The possible values for @var{style} are as follows, again where
  2482. supported by the system,
  2483. @defvar SOCK_STREAM
  2484. @defvarx SOCK_DGRAM
  2485. @defvarx SOCK_RAW
  2486. @defvarx SOCK_RDM
  2487. @defvarx SOCK_SEQPACKET
  2488. @end defvar
  2489. @var{proto} can be obtained from a protocol name using
  2490. @code{getprotobyname} (@pxref{Network Databases}). A value of zero
  2491. means the default protocol, which is usually right.
  2492. A socket cannot by used for communication until it has been connected
  2493. somewhere, usually with either @code{connect} or @code{accept} below.
  2494. @end deffn
  2495. @deffn {Scheme Procedure} socketpair family style proto
  2496. @deffnx {C Function} scm_socketpair (family, style, proto)
  2497. Return a pair, the @code{car} and @code{cdr} of which are two unnamed
  2498. socket ports connected to each other. The connection is full-duplex,
  2499. so data can be transferred in either direction between the two.
  2500. @var{family}, @var{style} and @var{proto} are as per @code{socket}
  2501. above. But many systems only support socket pairs in the
  2502. @code{PF_UNIX} family. Zero is likely to be the only meaningful value
  2503. for @var{proto}.
  2504. @end deffn
  2505. @deffn {Scheme Procedure} getsockopt sock level optname
  2506. @deffnx {Scheme Procedure} setsockopt sock level optname value
  2507. @deffnx {C Function} scm_getsockopt (sock, level, optname)
  2508. @deffnx {C Function} scm_setsockopt (sock, level, optname, value)
  2509. Get or set an option on socket port @var{sock}. @code{getsockopt}
  2510. returns the current value. @code{setsockopt} sets a value and the
  2511. return is unspecified.
  2512. @var{level} is an integer specifying a protocol layer, either
  2513. @code{SOL_SOCKET} for socket level options, or a protocol number from
  2514. the @code{IPPROTO} constants or @code{getprotoent} (@pxref{Network
  2515. Databases}).
  2516. @defvar SOL_SOCKET
  2517. @defvarx IPPROTO_IP
  2518. @defvarx IPPROTO_TCP
  2519. @defvarx IPPROTO_UDP
  2520. @end defvar
  2521. @var{optname} is an integer specifying an option within the protocol
  2522. layer.
  2523. For @code{SOL_SOCKET} level the following @var{optname}s are defined
  2524. (when provided by the system). For their meaning see
  2525. @ref{Socket-Level Options,,, libc, The GNU C Library Reference
  2526. Manual}, or @command{man 7 socket}.
  2527. @defvar SO_DEBUG
  2528. @defvarx SO_REUSEADDR
  2529. @defvarx SO_STYLE
  2530. @defvarx SO_TYPE
  2531. @defvarx SO_ERROR
  2532. @defvarx SO_DONTROUTE
  2533. @defvarx SO_BROADCAST
  2534. @defvarx SO_SNDBUF
  2535. @defvarx SO_RCVBUF
  2536. @defvarx SO_KEEPALIVE
  2537. @defvarx SO_OOBINLINE
  2538. @defvarx SO_NO_CHECK
  2539. @defvarx SO_PRIORITY
  2540. The @var{value} taken or returned is an integer.
  2541. @end defvar
  2542. @defvar SO_LINGER
  2543. The @var{value} taken or returned is a pair of integers
  2544. @code{(@var{ENABLE} . @var{TIMEOUT})}. On old systems without timeout
  2545. support (ie.@: without @code{struct linger}), only @var{ENABLE} has an
  2546. effect but the value in Guile is always a pair.
  2547. @end defvar
  2548. @c Note that we refer only to ``man ip'' here. On GNU/Linux it's
  2549. @c ``man 7 ip'' but on NetBSD it's ``man 4 ip''.
  2550. @c
  2551. For IP level (@code{IPPROTO_IP}) the following @var{optname}s are
  2552. defined (when provided by the system). See @command{man ip} for what
  2553. they mean.
  2554. @defvar IP_MULTICAST_IF
  2555. This sets the source interface used by multicast traffic.
  2556. @end defvar
  2557. @defvar IP_MULTICAST_TTL
  2558. This sets the default TTL for multicast traffic. This defaults
  2559. to 1 and should be increased to allow traffic to pass beyond the
  2560. local network.
  2561. @end defvar
  2562. @defvar IP_ADD_MEMBERSHIP
  2563. @defvarx IP_DROP_MEMBERSHIP
  2564. These can be used only with @code{setsockopt}, not @code{getsockopt}.
  2565. @var{value} is a pair @code{(@var{MULTIADDR} . @var{INTERFACEADDR})}
  2566. of integer IPv4 addresses (@pxref{Network Address Conversion}).
  2567. @var{MULTIADDR} is a multicast address to be added to or dropped from
  2568. the interface @var{INTERFACEADDR}. @var{INTERFACEADDR} can be
  2569. @code{INADDR_ANY} to have the system select the interface.
  2570. @var{INTERFACEADDR} can also be an interface index number, on systems
  2571. supporting that.
  2572. @end defvar
  2573. @end deffn
  2574. @deffn {Scheme Procedure} shutdown sock how
  2575. @deffnx {C Function} scm_shutdown (sock, how)
  2576. Sockets can be closed simply by using @code{close-port}. The
  2577. @code{shutdown} procedure allows reception or transmission on a
  2578. connection to be shut down individually, according to the parameter
  2579. @var{how}:
  2580. @table @asis
  2581. @item 0
  2582. Stop receiving data for this socket. If further data arrives, reject it.
  2583. @item 1
  2584. Stop trying to transmit data from this socket. Discard any
  2585. data waiting to be sent. Stop looking for acknowledgement of
  2586. data already sent; don't retransmit it if it is lost.
  2587. @item 2
  2588. Stop both reception and transmission.
  2589. @end table
  2590. The return value is unspecified.
  2591. @end deffn
  2592. @deffn {Scheme Procedure} connect sock sockaddr
  2593. @deffnx {Scheme Procedure} connect sock AF_INET ipv4addr port
  2594. @deffnx {Scheme Procedure} connect sock AF_INET6 ipv6addr port [flowinfo [scopeid]]
  2595. @deffnx {Scheme Procedure} connect sock AF_UNIX path
  2596. @deffnx {C Function} scm_connect (sock, fam, address, args)
  2597. Initiate a connection on socket port @var{sock} to a given address.
  2598. The destination is either a socket address object, or arguments the
  2599. same as @code{make-socket-address} would take to make such an object
  2600. (@pxref{Network Socket Address}). The return value is unspecified.
  2601. @example
  2602. (connect sock AF_INET INADDR_LOOPBACK 23)
  2603. (connect sock (make-socket-address AF_INET INADDR_LOOPBACK 23))
  2604. @end example
  2605. @end deffn
  2606. @deffn {Scheme Procedure} bind sock sockaddr
  2607. @deffnx {Scheme Procedure} bind sock AF_INET ipv4addr port
  2608. @deffnx {Scheme Procedure} bind sock AF_INET6 ipv6addr port [flowinfo [scopeid]]
  2609. @deffnx {Scheme Procedure} bind sock AF_UNIX path
  2610. @deffnx {C Function} scm_bind (sock, fam, address, args)
  2611. Bind socket port @var{sock} to the given address. The address is
  2612. either a socket address object, or arguments the same as
  2613. @code{make-socket-address} would take to make such an object
  2614. (@pxref{Network Socket Address}). The return value is unspecified.
  2615. Generally a socket is only explicitly bound to a particular address
  2616. when making a server, i.e.@: to listen on a particular port. For an
  2617. outgoing connection the system will assign a local address
  2618. automatically, if not already bound.
  2619. @example
  2620. (bind sock AF_INET INADDR_ANY 12345)
  2621. (bind sock (make-socket-address AF_INET INADDR_ANY 12345))
  2622. @end example
  2623. @end deffn
  2624. @deffn {Scheme Procedure} listen sock backlog
  2625. @deffnx {C Function} scm_listen (sock, backlog)
  2626. Enable @var{sock} to accept connection
  2627. requests. @var{backlog} is an integer specifying
  2628. the maximum length of the queue for pending connections.
  2629. If the queue fills, new clients will fail to connect until
  2630. the server calls @code{accept} to accept a connection from
  2631. the queue.
  2632. The return value is unspecified.
  2633. @end deffn
  2634. @deffn {Scheme Procedure} accept sock
  2635. @deffnx {C Function} scm_accept (sock)
  2636. Accept a connection from socket port @var{sock} which has been enabled
  2637. for listening with @code{listen} above. If there are no incoming
  2638. connections in the queue, wait until one is available (unless
  2639. @code{O_NONBLOCK} has been set on the socket, @pxref{Ports and File
  2640. Descriptors,@code{fcntl}}).
  2641. The return value is a pair. The @code{car} is a new socket port,
  2642. connected and ready to communicate. The @code{cdr} is a socket
  2643. address object (@pxref{Network Socket Address}) which is where the
  2644. remote connection is from (like @code{getpeername} below).
  2645. All communication takes place using the new socket returned. The
  2646. given @var{sock} remains bound and listening, and @code{accept} may be
  2647. called on it again to get another incoming connection when desired.
  2648. @end deffn
  2649. @deffn {Scheme Procedure} getsockname sock
  2650. @deffnx {C Function} scm_getsockname (sock)
  2651. Return a socket address object which is the where @var{sock} is bound
  2652. locally. @var{sock} may have obtained its local address from
  2653. @code{bind} (above), or if a @code{connect} is done with an otherwise
  2654. unbound socket (which is usual) then the system will have assigned an
  2655. address.
  2656. Note that on many systems the address of a socket in the
  2657. @code{AF_UNIX} namespace cannot be read.
  2658. @end deffn
  2659. @deffn {Scheme Procedure} getpeername sock
  2660. @deffnx {C Function} scm_getpeername (sock)
  2661. Return a socket address object which is where @var{sock} is connected
  2662. to, i.e.@: the remote endpoint.
  2663. Note that on many systems the address of a socket in the
  2664. @code{AF_UNIX} namespace cannot be read.
  2665. @end deffn
  2666. @deffn {Scheme Procedure} recv! sock buf [flags]
  2667. @deffnx {C Function} scm_recv (sock, buf, flags)
  2668. Receive data from a socket port.
  2669. @var{sock} must already
  2670. be bound to the address from which data is to be received.
  2671. @var{buf} is a bytevector into which
  2672. the data will be written. The size of @var{buf} limits
  2673. the amount of
  2674. data which can be received: in the case of packet
  2675. protocols, if a packet larger than this limit is encountered
  2676. then some data
  2677. will be irrevocably lost.
  2678. @vindex MSG_OOB
  2679. @vindex MSG_PEEK
  2680. @vindex MSG_DONTROUTE
  2681. The optional @var{flags} argument is a value or bitwise OR of
  2682. @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
  2683. The value returned is the number of bytes read from the
  2684. socket.
  2685. Note that the data is read directly from the socket file
  2686. descriptor:
  2687. any unread buffered port data is ignored.
  2688. @end deffn
  2689. @deffn {Scheme Procedure} send sock message [flags]
  2690. @deffnx {C Function} scm_send (sock, message, flags)
  2691. @vindex MSG_OOB
  2692. @vindex MSG_PEEK
  2693. @vindex MSG_DONTROUTE
  2694. Transmit bytevector @var{message} on socket port @var{sock}.
  2695. @var{sock} must already be bound to a destination address. The value
  2696. returned is the number of bytes transmitted---it's possible for this
  2697. to be less than the length of @var{message} if the socket is set to be
  2698. non-blocking. The optional @var{flags} argument is a value or bitwise
  2699. OR of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
  2700. Note that the data is written directly to the socket
  2701. file descriptor:
  2702. any unflushed buffered port data is ignored.
  2703. @end deffn
  2704. @deffn {Scheme Procedure} recvfrom! sock buf [flags [start [end]]]
  2705. @deffnx {C Function} scm_recvfrom (sock, buf, flags, start, end)
  2706. Receive data from socket port @var{sock}, returning the originating
  2707. address as well as the data. This function is usually for datagram
  2708. sockets, but can be used on stream-oriented sockets too.
  2709. The data received is stored in bytevector @var{buf}, using
  2710. either the whole bytevector or just the region between the optional
  2711. @var{start} and @var{end} positions. The size of @var{buf}
  2712. limits the amount of data that can be received. For datagram
  2713. protocols if a packet larger than this is received then excess
  2714. bytes are irrevocably lost.
  2715. The return value is a pair. The @code{car} is the number of bytes
  2716. read. The @code{cdr} is a socket address object (@pxref{Network
  2717. Socket Address}) which is where the data came from, or @code{#f} if
  2718. the origin is unknown.
  2719. @vindex MSG_OOB
  2720. @vindex MSG_PEEK
  2721. @vindex MSG_DONTROUTE
  2722. The optional @var{flags} argument is a or bitwise-OR (@code{logior})
  2723. of @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
  2724. Data is read directly from the socket file descriptor, any buffered
  2725. port data is ignored.
  2726. @c This was linux kernel 2.6.15 and glibc 2.3.6, not sure what any
  2727. @c specs are supposed to say about recvfrom threading.
  2728. @c
  2729. On a GNU/Linux system @code{recvfrom!} is not multi-threading, all
  2730. threads stop while a @code{recvfrom!} call is in progress. An
  2731. application may need to use @code{select}, @code{O_NONBLOCK} or
  2732. @code{MSG_DONTWAIT} to avoid this.
  2733. @end deffn
  2734. @deffn {Scheme Procedure} sendto sock message sockaddr [flags]
  2735. @deffnx {Scheme Procedure} sendto sock message AF_INET ipv4addr port [flags]
  2736. @deffnx {Scheme Procedure} sendto sock message AF_INET6 ipv6addr port [flowinfo [scopeid [flags]]]
  2737. @deffnx {Scheme Procedure} sendto sock message AF_UNIX path [flags]
  2738. @deffnx {C Function} scm_sendto (sock, message, fam, address, args_and_flags)
  2739. Transmit bytevector @var{message} as a datagram socket port
  2740. @var{sock}. The destination is specified either as a socket address
  2741. object, or as arguments the same as would be taken by
  2742. @code{make-socket-address} to create such an object (@pxref{Network
  2743. Socket Address}).
  2744. The destination address may be followed by an optional @var{flags}
  2745. argument which is a @code{logior} (@pxref{Bitwise Operations}) of
  2746. @code{MSG_OOB}, @code{MSG_PEEK}, @code{MSG_DONTROUTE} etc.
  2747. The value returned is the number of bytes transmitted --
  2748. it's possible for
  2749. this to be less than the length of @var{message} if the
  2750. socket is
  2751. set to be non-blocking.
  2752. Note that the data is written directly to the socket
  2753. file descriptor:
  2754. any unflushed buffered port data is ignored.
  2755. @end deffn
  2756. The following functions can be used to convert short and long integers
  2757. between ``host'' and ``network'' order. Although the procedures above do
  2758. this automatically for addresses, the conversion will still need to
  2759. be done when sending or receiving encoded integer data from the network.
  2760. @deffn {Scheme Procedure} htons value
  2761. @deffnx {C Function} scm_htons (value)
  2762. Convert a 16 bit quantity from host to network byte ordering.
  2763. @var{value} is packed into 2 bytes, which are then converted
  2764. and returned as a new integer.
  2765. @end deffn
  2766. @deffn {Scheme Procedure} ntohs value
  2767. @deffnx {C Function} scm_ntohs (value)
  2768. Convert a 16 bit quantity from network to host byte ordering.
  2769. @var{value} is packed into 2 bytes, which are then converted
  2770. and returned as a new integer.
  2771. @end deffn
  2772. @deffn {Scheme Procedure} htonl value
  2773. @deffnx {C Function} scm_htonl (value)
  2774. Convert a 32 bit quantity from host to network byte ordering.
  2775. @var{value} is packed into 4 bytes, which are then converted
  2776. and returned as a new integer.
  2777. @end deffn
  2778. @deffn {Scheme Procedure} ntohl value
  2779. @deffnx {C Function} scm_ntohl (value)
  2780. Convert a 32 bit quantity from network to host byte ordering.
  2781. @var{value} is packed into 4 bytes, which are then converted
  2782. and returned as a new integer.
  2783. @end deffn
  2784. These procedures are inconvenient to use at present, but consider:
  2785. @example
  2786. (define write-network-long
  2787. (lambda (value port)
  2788. (let ((v (make-uniform-vector 1 1 0)))
  2789. (uniform-vector-set! v 0 (htonl value))
  2790. (uniform-vector-write v port))))
  2791. (define read-network-long
  2792. (lambda (port)
  2793. (let ((v (make-uniform-vector 1 1 0)))
  2794. (uniform-vector-read! v port)
  2795. (ntohl (uniform-vector-ref v 0)))))
  2796. @end example
  2797. @node Internet Socket Examples
  2798. @subsubsection Network Socket Examples
  2799. @cindex network examples
  2800. @cindex socket examples
  2801. The following give examples of how to use network sockets.
  2802. @subsubheading Internet Socket Client Example
  2803. @cindex socket client example
  2804. The following example demonstrates an Internet socket client.
  2805. It connects to the HTTP daemon running on the local machine and
  2806. returns the contents of the root index URL.
  2807. @example
  2808. (let ((s (socket PF_INET SOCK_STREAM 0)))
  2809. (connect s AF_INET (inet-pton AF_INET "127.0.0.1") 80)
  2810. (display "GET / HTTP/1.0\r\n\r\n" s)
  2811. (do ((line (read-line s) (read-line s)))
  2812. ((eof-object? line))
  2813. (display line)
  2814. (newline)))
  2815. @end example
  2816. @subsubheading Internet Socket Server Example
  2817. @cindex socket server example
  2818. The following example shows a simple Internet server which listens on
  2819. port 2904 for incoming connections and sends a greeting back to the
  2820. client.
  2821. @example
  2822. (let ((s (socket PF_INET SOCK_STREAM 0)))
  2823. (setsockopt s SOL_SOCKET SO_REUSEADDR 1)
  2824. ;; @r{Specific address?}
  2825. ;; @r{(bind s AF_INET (inet-pton AF_INET "127.0.0.1") 2904)}
  2826. (bind s AF_INET INADDR_ANY 2904)
  2827. (listen s 5)
  2828. (simple-format #t "Listening for clients in pid: ~S" (getpid))
  2829. (newline)
  2830. (while #t
  2831. (let* ((client-connection (accept s))
  2832. (client-details (cdr client-connection))
  2833. (client (car client-connection)))
  2834. (simple-format #t "Got new client connection: ~S"
  2835. client-details)
  2836. (newline)
  2837. (simple-format #t "Client address: ~S"
  2838. (gethostbyaddr
  2839. (sockaddr:addr client-details)))
  2840. (newline)
  2841. ;; @r{Send back the greeting to the client port}
  2842. (display "Hello client\r\n" client)
  2843. (close client))))
  2844. @end example
  2845. @node System Identification
  2846. @subsection System Identification
  2847. @cindex system name
  2848. This section lists the various procedures Guile provides for accessing
  2849. information about the system it runs on.
  2850. @deffn {Scheme Procedure} uname
  2851. @deffnx {C Function} scm_uname ()
  2852. Return an object with some information about the computer
  2853. system the program is running on.
  2854. The following procedures accept an object as returned by @code{uname}
  2855. and return a selected component (all of which are strings).
  2856. @deffn {Scheme Procedure} utsname:sysname un
  2857. The name of the operating system.
  2858. @end deffn
  2859. @deffn {Scheme Procedure} utsname:nodename un
  2860. The network name of the computer.
  2861. @end deffn
  2862. @deffn {Scheme Procedure} utsname:release un
  2863. The current release level of the operating system implementation.
  2864. @end deffn
  2865. @deffn {Scheme Procedure} utsname:version un
  2866. The current version level within the release of the operating system.
  2867. @end deffn
  2868. @deffn {Scheme Procedure} utsname:machine un
  2869. A description of the hardware.
  2870. @end deffn
  2871. @end deffn
  2872. @deffn {Scheme Procedure} gethostname
  2873. @deffnx {C Function} scm_gethostname ()
  2874. @cindex host name
  2875. Return the host name of the current processor.
  2876. @end deffn
  2877. @deffn {Scheme Procedure} sethostname name
  2878. @deffnx {C Function} scm_sethostname (name)
  2879. Set the host name of the current processor to @var{name}. May
  2880. only be used by the superuser. The return value is not
  2881. specified.
  2882. @end deffn
  2883. @node Locales
  2884. @subsection Locales
  2885. @cindex locale
  2886. @deffn {Scheme Procedure} setlocale category [locale]
  2887. @deffnx {C Function} scm_setlocale (category, locale)
  2888. Get or set the current locale, used for various internationalizations.
  2889. Locales are strings, such as @samp{sv_SE}.
  2890. If @var{locale} is given then the locale for the given @var{category}
  2891. is set and the new value returned. If @var{locale} is not given then
  2892. the current value is returned. @var{category} should be one of the
  2893. following values (@pxref{Locale Categories, Categories of Activities
  2894. that Locales Affect,, libc, The GNU C Library Reference Manual}):
  2895. @defvar LC_ALL
  2896. @defvarx LC_COLLATE
  2897. @defvarx LC_CTYPE
  2898. @defvarx LC_MESSAGES
  2899. @defvarx LC_MONETARY
  2900. @defvarx LC_NUMERIC
  2901. @defvarx LC_TIME
  2902. @end defvar
  2903. @cindex @code{LANG}
  2904. A common usage is @samp{(setlocale LC_ALL "")}, which initializes all
  2905. categories based on standard environment variables (@code{LANG} etc).
  2906. For full details on categories and locale names @pxref{Locales,,
  2907. Locales and Internationalization, libc, The GNU C Library Reference
  2908. Manual}.
  2909. Note that @code{setlocale} affects locale settings for the whole
  2910. process. @xref{i18n Introduction, locale objects and
  2911. @code{make-locale}}, for a thread-safe alternative.
  2912. @end deffn
  2913. @node Encryption
  2914. @subsection Encryption
  2915. @cindex encryption
  2916. Please note that the procedures in this section are not suited for
  2917. strong encryption, they are only interfaces to the well-known and
  2918. common system library functions of the same name. They are just as good
  2919. (or bad) as the underlying functions, so you should refer to your system
  2920. documentation before using them (@pxref{crypt,, Encrypting Passwords,
  2921. libc, The GNU C Library Reference Manual}).
  2922. @deffn {Scheme Procedure} crypt key salt
  2923. @deffnx {C Function} scm_crypt (key, salt)
  2924. Encrypt @var{key}, with the addition of @var{salt} (both strings),
  2925. using the @code{crypt} C library call.
  2926. @end deffn
  2927. Although @code{getpass} is not an encryption procedure per se, it
  2928. appears here because it is often used in combination with @code{crypt}:
  2929. @deffn {Scheme Procedure} getpass prompt
  2930. @deffnx {C Function} scm_getpass (prompt)
  2931. @cindex password
  2932. Display @var{prompt} to the standard error output and read
  2933. a password from @file{/dev/tty}. If this file is not
  2934. accessible, it reads from standard input. The password may be
  2935. up to 127 characters in length. Additional characters and the
  2936. terminating newline character are discarded. While reading
  2937. the password, echoing and the generation of signals by special
  2938. characters is disabled.
  2939. @end deffn
  2940. @c Local Variables:
  2941. @c TeX-master: "guile.texi"
  2942. @c End: