source: project/chicken/branches/prerelease/manual/Unit posix @ 9381

Last change on this file since 9381 was 9381, checked in by Ivan Raikov, 12 years ago

Merged trunk into prerelease

File size: 38.5 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Unit posix
5
6This unit provides services as used on many UNIX-like systems.  Note that
7the following definitions are not all available on non-UNIX systems like
8Windows. See below for Windows specific notes.
9
10This unit uses the {{regex}}, {{scheduler}}, {{extras}} and {{utils}} units.
11
12All errors related to failing file-operations will signal a condition
13of kind {{(exn i/o file)}}.
14
15
16=== Constants
17
18==== File-control Commands
19
20===== fcntl/dupfd
21===== fcntl/getfd
22===== fcntl/setfd
23===== fcntl/getfl
24===== fcntl/setfl
25
26==== Standard I/O file-descriptors
27
28===== fileno/stdin
29===== fileno/stdout
30===== fileno/stderr
31
32==== Open flags
33
34===== open/rdonly
35===== open/wronly
36===== open/rdwr
37===== open/read
38===== open/write
39===== open/creat
40===== open/append
41===== open/excl
42===== open/noctty
43===== open/nonblock
44===== open/trunc
45===== open/sync
46===== open/fsync
47===== open/binary
48===== open/text
49
50==== Permission bits
51
52===== perm/irusr
53===== perm/iwusr
54===== perm/ixusr
55===== perm/irgrp
56===== perm/iwgrp
57===== perm/ixgrp
58===== perm/iroth
59===== perm/iwoth
60===== perm/ixoth
61===== perm/irwxu
62===== perm/irwxg
63===== perm/irwxo
64===== perm/isvtx
65===== perm/isuid
66===== perm/isgid
67
68
69=== Directories
70
71==== change-directory
72
73 [procedure] (change-directory NAME)
74
75Changes the current working directory to {{NAME}}.
76
77==== current-directory
78
79 [procedure] (current-directory [DIR])
80
81Returns the name of the current working directory. If the optional argument {{DIR}} is given,
82then {{(current-directory DIR)}} is equivalent to {{(change-directory DIR)}}.
83
84==== create-directory
85
86 [procedure] (create-directory NAME)
87
88Creates a directory with the pathname {{NAME}}.
89
90==== delete-directory
91
92 [procedure] (delete-directory NAME)
93
94Deletes the directory with the pathname {{NAME}}. The directory has
95to be empty.
96
97==== directory
98
99 [procedure] (directory [PATHNAME [SHOW-DOTFILES?]])
100
101Returns a list with all files that are contained in the directory with the name {{PATHNAME}}
102(which defaults to the value of {{(current-directory)}}).
103Files beginning with {{.}} are included only if {{SHOW-DOTFILES?}} is given and not {{#f}}.
104
105==== directory?
106
107 [procedure] (directory? NAME)
108
109Returns {{#t}} if there exists a file with the name {{NAME}}
110and if that file is a directory, or {{#f}} otherwise.
111
112==== glob
113
114 [procedure] (glob PATTERN1 ...)
115
116Returns a list of the pathnames of all existing files matching
117{{PATTERN1 ...}}, which should be strings containing the usual
118file-patterns (with {{*}} matching zero or more characters and
119{{?}} matching zero or one character).
120
121==== set-root-directory!
122
123 [procedure] (set-root-directory! STRING)
124
125Sets the root directory for the current process to the path given in {{STRING}}
126(using the {{chroot}} function).
127If the current process has no root permissions, the operation will fail.
128
129
130=== Pipes
131
132==== call-with-input-pipe
133==== call-with-output-pipe
134
135 [procedure] (call-with-input-pipe CMDLINE PROC [MODE])
136 [procedure] (call-with-output-pipe CMDLINE PROC [MODE])
137
138Call {{PROC}} with a single argument: a input- or output port
139for a pipe connected to the subprocess named in {{CMDLINE}}. If
140{{PROC}} returns normally, the pipe is closed and any result values
141are returned.
142
143==== close-input-pipe
144==== close-output-pipe
145
146 [procedure] (close-input-pipe PORT)
147 [procedure] (close-output-pipe PORT)
148
149Closes the pipe given in {{PORT}} and waits until the connected
150subprocess finishes. The exit-status code of the invoked process
151is returned.
152
153==== create-pipe
154
155 [procedure] (create-pipe)
156
157The fundamental pipe-creation operator. Calls the C function
158{{pipe()}} and returns 2 values: the file-descriptors of the input-
159and output-ends of the pipe.
160
161==== open-input-pipe
162
163 [procedure] (open-input-pipe CMDLINE [MODE])
164
165Spawns a subprocess with the command-line string {{CMDLINE}} and
166returns a port, from which the output of the process can be read. If
167{{MODE}} is specified, it should be the keyword {{#:text}}
168(the default) or {{#:binary}}.
169
170==== open-output-pipe
171
172 [procedure] (open-output-pipe CMDLINE [MODE])
173
174Spawns a subprocess with the command-line string {{CMDLINE}} and
175returns a port. Anything written to that port is treated as the input
176for the process.  If {{MODE}} is specified, it should be the keyword
177{{#:text}} (the default) or {{#:binary}}.
178
179==== pipe/buf
180This variable contains the maximal number of bytes that can be written
181atomically into a pipe or FIFO.
182
183==== with-input-from-pipe
184==== with-output-to-pipe
185
186 [procedure] (with-input-from-pipe CMDLINE THUNK [MODE])
187 [procedure] (with-output-to-pipe CMDLINE THUNK [MODE])
188
189Temporarily set the value of
190{{current-input-port/current-output-port}} to a port for a
191pipe connected to the subprocess named in {{CMDLINE}} and call
192the procedure {{THUNK}} with no arguments. After {{THUNK}}
193returns normally the pipe is closed and the standard input-/output port
194is restored to its previous value and any result values are returned.
195
196<enscript highlight=scheme>
197(with-output-to-pipe
198  "gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"
199  (lambda ()
200    (print #<<EOF
201 %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@xx.xxxxxx.xx.xx>
202 /C/neg/d/mul/R/rlineto/E/exp/H{{cvx def}repeat}def/T/dup/g/gt/r/roll/J/ifelse 8
203 H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
204 X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
205 F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
206 Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
207 ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
208 V1c&j2AYdjmMdjjd!o&1r!M){( )T 0 4 3 r put T(/)g{T(9)g{cvn}{cvi}J}{($)g[]J}J
209 cvx}forall/moveto/p/floor/w/div/S/add 29 H[{[{]setgray fill}for Y}for showpage
210 EOF
211 ) ) )
212</enscript>
213
214
215=== Fifos
216
217==== create-fifo
218
219 [procedure] (create-fifo FILENAME [MODE])
220
221Creates a FIFO with the name {{FILENAME}} and the permission bits
222{{MODE}}, which defaults to
223
224<enscript highlight=scheme>
225 [procedure] (+ perm/irwxu perm/irwxg perm/irwxo)
226</enscript>
227
228==== fifo?
229
230 [procedure] (fifo? FILENAME)
231
232Returns {{#t}} if the file with the name {{FILENAME}} names
233a FIFO.
234
235
236=== File descriptors and low-level I/O
237
238==== duplicate-fileno
239
240 [procedure] (duplicate-fileno OLD [NEW])
241
242If {{NEW}} is given, then the file-descriptor {{NEW}} is opened
243to access the file with the file-descriptor {{OLD}}. Otherwise a
244fresh file-descriptor accessing the same file as {{OLD}} is returned.
245
246==== file-close
247
248 [procedure] (file-close FILENO)
249
250Closes the input/output file with the file-descriptor {{FILENO}}.
251
252==== file-open
253
254 [procedure] (file-open FILENAME FLAGS [MODE])
255
256Opens the file specified with the string {{FILENAME}} and open-flags
257{{FLAGS}} using the C function {{open()}}. On success a
258file-descriptor for the opened file is returned.  {{FLAGS}}
259should be a bitmask containing one or more of the {{open/...}}
260values '''or'''ed together using {{bitwise-ior}} (or simply added
261together).  The optional {{MODE}} should be a bitmask composed of one
262or more permission values like {{perm/irusr}} and is only relevant
263when a new file is created. The default mode is
264{{perm/irwxu | perm/irgrp | perm/iroth}}.
265
266==== file-mkstemp
267
268 [procedure] (file-mkstemp TEMPLATE-FILENAME)
269
270Create a file based on the given {{TEMPLATE-FILENAME}}, in which
271the six last characters must be ''XXXXXX''.  These will be replaced
272with a string that makes the filename unique.  The file descriptor of
273the created file and the generated filename is returned.  See the
274{{mkstemp(3)}} manual page for details on how this function
275works.  The template string given is not modified.
276
277Example usage:
278
279<enscript highlight=scheme>
280 (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
281  (let ((temp-port (open-output-file* fd)))
282    (format temp-port "This file is ~A.~%" temp-path)
283    (close-output-port temp-port)))
284</enscript>
285
286==== file-read
287
288 [procedure] (file-read FILENO SIZE [BUFFER])
289
290Reads {{SIZE}} bytes from the file with the file-descriptor
291{{FILENO}}.  If a string or bytevector is passed in the optional
292argument {{BUFFER}}, then this string will be destructively modified
293to contain the read data. This procedure returns a list with two values:
294the buffer containing the data and the number of bytes read.
295
296==== file-select
297
298 [procedure] (file-select READFDLIST WRITEFDLIST [TIMEOUT])
299
300Waits until any of the file-descriptors given in the lists
301{{READFDLIST}} and {{WRITEFDLIST}} is ready for input or
302output, respectively. If the optional argument {{TIMEOUT}} is
303given and not false, then it should specify the number of seconds after
304which the wait is to be aborted (the value may be a floating point
305number). This procedure returns two values:
306the lists of file-descriptors ready for input and output, respectively.
307{{READFDLIST}} and '''WRITEFDLIST''' may also by file-descriptors
308instead of lists.  In this case the returned values are booleans
309indicating whether input/output is ready by {{#t}} or {{#f}}
310otherwise.  You can also pass {{#f}} as {{READFDLIST}} or
311{{WRITEFDLIST}} argument, which is equivalent to {{()}}.
312
313==== file-write
314
315 [procedure] (file-write FILENO BUFFER [SIZE])
316
317Writes the contents of the string or bytevector {{BUFFER}} into
318the file with the file-descriptor {{FILENO}}. If the optional
319argument {{SIZE}} is given, then only the specified number of bytes
320are written.
321
322==== file-control
323
324 [procedure] (file-control FILENO COMMAND [ARGUMENT])
325
326Performs the fcntl operation {{COMMAND}} with the given
327{{FILENO}} and optional {{ARGUMENT}}. The return value is
328meaningful depending on the {{COMMAND}}.
329
330==== open-input-file*
331==== open-output-file*
332
333 [procedure] (open-input-file* FILENO [OPENMODE])
334 [procedure] (open-output-file* FILENO [OPENMODE])
335
336Opens file for the file-descriptor {{FILENO}} for input or output
337and returns a port.  {{FILENO}} should be a positive exact integer.
338{{OPENMODE}} specifies an additional mode for opening the file
339(currently only the keyword {{#:append}} is supported, which opens
340an output-file for appending).
341
342==== port->fileno
343
344 [procedure] (port->fileno PORT)
345
346If {{PORT}} is a file- or tcp-port, then a file-descriptor is returned for
347this port. Otherwise an error is signaled.
348
349
350=== Retrieving file attributes
351
352==== file-access-time
353==== file-change-time
354==== file-modification-time
355
356 [procedure] (file-access-time FILE)
357 [procedure] (file-change-time FILE)
358 [procedure] (file-modification-time FILE)
359
360Returns time (in seconds) of the last access, modification or change of {{FILE}}. {{FILE}}
361may be a filename or a file-descriptor. If the file does not exist,
362an error is signaled.
363
364==== file-stat
365
366 [procedure] (file-stat FILE [LINK])
367
368Returns a 13-element vector with the following contents: inode-number,
369mode (as with {{file-permissions}}), number of hard links, uid of
370owner (as with {{file-owner}}), gid of owner, size (as with
371{{file-size}}) and access-, change- and modification-time (as with
372{{file-access-time}}, {{file-change-time}} and
373{{file-modification-time}}, device id, device type (for special file
374inode, blocksize and blocks allocated.  On Windows systems the last 4
375values are undefined.  If the optional argument {{LINK}} is given and
376not {{#f}}, then the file-statistics vector will be resolved for
377symbolic links (otherwise symbolic links are not resolved).
378Note that for very large files, the {{file-size}} value may be an
379inexact integer.
380
381==== file-position
382
383 [procedure] (file-position FILE)
384
385Returns the current file position of {{FILE}}, which should be a
386port or a file-descriptor.
387
388==== file-size
389
390 [procedure] (file-size FILENAME)
391
392Returns the size of the file designated by {{FILE}}.  {{FILE}}
393may be a filename or a file-descriptor.  If the file does not exist,
394an error is signaled. Note that for very large files, {{file-size}} may
395return an inexact integer.
396
397==== regular-file?
398
399 [procedure] (regular-file? FILENAME)
400
401Returns true, if {{FILENAME}} names a regular file (not a directory or symbolic link).
402
403==== file-owner
404
405 [procedure] (file-owner FILE)
406
407Returns the user-id of {{FILE}}.  {{FILE}} may be a filename
408or a file-descriptor.
409
410==== file-permissions
411
412 [procedure] (file-permissions FILE)
413
414Returns the permission bits for {{FILE}}. You can test this value
415by performing bitwise operations on the result and the {{perm/...}}
416values.  {{FILE}} may be a filename or a file-descriptor.
417
418==== file-read-access?
419==== file-write-access?
420==== file-execute-access?
421
422 [procedure] (file-read-access? FILENAME)
423 [procedure] (file-write-access? FILENAME)
424 [procedure] (file-execute-access? FILENAME)
425
426These procedures return {{#t}} if the current user has read,
427write or execute permissions on the file named {{FILENAME}}.
428
429
430=== Changing file attributes
431
432==== file-truncate
433
434 [procedure] (file-truncate FILE OFFSET)
435
436Truncates the file {{FILE}} to the length {{OFFSET}},
437which should be an integer. If the file-size is smaller or equal to
438{{OFFSET}} then nothing is done.  {{FILE}} should be a filename
439or a file-descriptor.
440
441==== set-file-position!
442
443 [procedure] (set-file-position! FILE POSITION [WHENCE])
444 [procedure] (set! (file-position FILE) POSITION)
445
446Sets the current read/write position of {{FILE}} to
447{{POSITION}}, which should be an exact integer. {{FILE}}
448should be a port or a file-descriptor.  {{WHENCE}} specifies
449how the position is to interpreted and should be one of the values
450{{seek/set, seek/cur}} and {{seek/end}}. It defaults to
451{{seek/set}}.
452
453Exceptions: {{(exn bounds)}}, {{(exn i/o file)}}
454
455==== change-file-mode
456
457 [procedure] (change-file-mode FILENAME MODE)
458
459Changes the current file mode of the file named {{FILENAME}}
460to {{MODE}} using the {{chmod()}} system call.  The
461{{perm/...}} variables contain the various permission bits and can
462be combinded with the {{bitwise-ior}} procedure.
463
464==== change-file-owner
465
466 [procedure] (change-file-owner FILENAME UID GID)
467
468Changes the owner information of the file named {{FILENAME}} to
469the user- and group-ids {{UID}} and {{GID}} (which should be
470exact integers) using the {{chown()}} system call.
471
472
473=== Processes
474
475==== current-process-id
476
477 [procedure] (current-process-id)
478
479Returns the process ID of the current process.
480
481==== parent-process-id
482
483 [procedure] (parent-process-id)
484
485Returns the process ID of the parent of the current process.
486
487==== process-group-id
488
489 [procedure] (process-group-id PID)
490
491Returns the process group ID of the process specified by {{PID}}.
492
493==== process-execute
494
495 [procedure] (process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST]])
496
497Creates a new child process and replaces the running process with it
498using the C library function {{execvp(3)}}. If the optional argument
499{{ARGUMENT-LIST}} is given, then it should contain a list of strings which
500are passed as arguments to the subprocess. If the optional argument
501{{ENVIRONMENT-LIST}} is supplied, then the library function {{execve(2)}}
502is used, and the environment passed in {{ENVIRONMENT-LIST}} (which should
503be of the form {{("<NAME>=<VALUE>" ...)}} is given
504to the invoked process. Note that {{execvp(3)}} respects the current setting
505of the {{PATH}} environment variable while {{execve(3)}} does not.
506
507==== process-fork
508
509 [procedure] (process-fork [THUNK])
510
511Creates a new child process with the UNIX system call
512{{fork()}}. Returns either the PID of the child process or 0. If
513{{THUNK}} is given, then the child process calls it as a procedure
514with no arguments and terminates.
515
516==== process-run
517
518 [procedure] (process-run COMMANDLINE])
519 [procedure] (process-run COMMAND ARGUMENT-LIST)
520
521Creates a new child process. The PID of the new process is returned.
522
523* The single parameter version passes the {{COMMANDLINE}} to the system shell, so usual
524argument expansion can take place.
525* The multiple parameter version directly invokes the {{COMMAND}} with the {{ARGUMENT-LIST}}.
526
527==== process-signal
528
529 [procedure] (process-signal PID [SIGNAL])
530
531Sends {{SIGNAL}} to the process with the id {{PID}} using the
532UNIX system call {{kill()}}. {{SIGNAL}} defaults to the value
533of the variable {{signal/term}}.
534
535==== process-wait
536
537 [procedure] (process-wait [PID [NOHANG]])
538
539Suspends the current process until the child process with
540the id {{PID}} has terminated using the UNIX system call
541{{waitpid()}}. If {{PID}} is not given, then this procedure
542waits for any child process. If {{NOHANG}} is given and not
543{{#f}} then the current process is not suspended.  This procedure
544returns three values:
545
546* {{PID}} or 0, if {{NOHANG}} is true and the child process has not terminated yet.
547* {{#t}} if the process exited normally or {{#f}} otherwise.
548* either the exit status, if the process terminated normally or the signal number that terminated/stopped the process.
549
550==== process
551
552 [procedure] (process COMMANDLINE)
553 [procedure] (process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])
554
555Creates a subprocess and returns three values: an input port from
556which data written by the sub-process can be read, an output port from
557which any data written to will be received as input in the sub-process
558and the process-id of the started sub-process. Blocking reads and writes
559to or from the ports returned by {{process}} only block the current
560thread, not other threads executing concurrently.
561
562* The single parameter version passes the string {{COMMANDLINE}} to the host-system's shell that
563is invoked as a subprocess.
564* The multiple parameter version directly invokes the {{COMMAND}} as a subprocess. The {{ARGUMENT-LIST}}
565is directly passed, as is {{ENVIRONMENT-LIST}}.
566
567Not using the shell may be preferrable for security reasons.
568
569==== process*
570
571 [procedure] (process* COMMANDLINE)
572 [procedure] (process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST])
573
574Like {{process}} but returns 4 values: an input port from
575which data written by the sub-process can be read, an output port from
576which any data written to will be received as input in the sub-process,
577the process-id of the started sub-process, and an input port from
578which data written by the sub-process to {{stderr}} can be read.
579
580==== sleep
581
582 [procedure] (sleep SECONDS)
583
584Puts the process to sleep for {{SECONDS}}. Returns either 0 if
585the time has completely elapsed, or the number of remaining seconds,
586if a signal occurred.
587
588==== create-session
589
590 [procedure] (create-session)
591
592Creates a new session if the calling process is not a process group leader and returns
593the session ID.
594
595
596=== Hard and symbolic links
597
598==== symbolic-link?
599
600 [procedure] (symbolic-link? FILENAME)
601
602Returns true, if {{FILENAME}} names a symbolic link.
603
604==== create-symbolic-link
605
606 [procedure] (create-symbolic-link OLDNAME NEWNAME)
607
608Creates a symbolic link with the filename {{NEWNAME}} that points
609to the file named {{OLDNAME}}.
610
611==== read-symbolic-link
612
613 [procedure] (read-symbolic-link FILENAME)
614
615Returns the filename to which the symbolic link {{FILENAME}} points.
616
617==== file-link
618
619 [procedure] (file-link OLDNAME NEWNAME)
620
621Creates a hard link from {{OLDNAME}} to {{NEWNAME}} (both strings).
622
623
624=== Retrieving user & group information
625
626==== current-user-id
627
628 [procedure] (current-user-id)
629 [setter] (set! (current-user-id) UID)
630
631Get or set the real user-id of the current process.
632
633==== current-effective-user-id
634
635 [procedure] (current-effective-user-id)
636 [setter] (set! (current-effective-user-id) UID)
637
638Get or set the effective user-id of the current process.
639
640==== user-information
641
642 [procedure] (user-information USER [AS-VECTOR])
643
644If {{USER}} specifes a valid username (as a string) or user ID, then the user
645database is consulted and a list of 7 values are returned: the user-name, the
646encrypted password, the user ID, the group ID, a user-specific string, the home
647directory and the default shell. When {{AS-VECTOR}} is {{#t}} a vector of 7
648elements is returned instead of a list. If no user with this name or id then
649{{#f}} is returned.
650
651==== current-group-id
652
653 [procedure] (current-group-id)
654 [setter] (set! (current-group-id) GID)
655
656Get or set the real group-id of the current process.
657
658==== current-effective-group-id
659
660 [procedure] (current-effective-group-id)
661 [setter] (set! (current-effective-group-id) GID)
662
663Get or set the effective group-id of the current process.
664ID can be found, then {{#f}} is returned.
665
666==== group-information
667
668 [procedure] (group-information GROUP)
669
670If {{GROUP}} specifies a valid group-name or group-id, then this
671procedure returns a list of four values: the group-name, the encrypted group password,
672the group ID and a list of the names of all group members. If no group with the
673given name or ID exists, then {{#f}} is returned.
674
675==== get-groups
676
677 [procedure] (get-groups)
678
679Returns a list with the supplementary group IDs of the current user.
680
681
682=== Changing user & group information
683
684==== set-groups!
685
686 [procedure] (set-groups! GIDLIST)
687
688Sets the supplementrary group IDs of the current user to the IDs given in the list {{GIDLIST}}.
689
690Only the superuser may invoke this procedure.
691
692==== initialize-groups
693
694 [procedure] (initialize-groups USERNAME BASEGID)
695
696Sets the supplementrary group IDs of the current user to the IDs from the user with name {{USERNAME}}
697(a string), including {{BASEGID}}.
698
699Only the superuser may invoke this procedure.
700
701==== set-process-group-id!
702
703 [procedure] (set-process-group-id! PID PGID)
704 [setter] (set! (process-group-id PID) PGID)
705
706Sets the process group ID of the process specifed by {{PID}} to {{PGID}}.
707
708
709=== Record locking
710
711==== file-lock
712
713 [procedure] (file-lock PORT [START [LEN]])
714
715Locks the file associated with {{PORT}} for reading or
716writing (according to whether {{PORT}} is an input- or
717output-port). {{START}} specifies the starting position in the
718file to be locked and defaults to 0. {{LEN}} specifies the length
719of the portion to be locked and defaults to {{#t}}, which means
720the complete file. {{file-lock}} returns a ''lock''-object.
721
722==== file-lock/blocking
723
724 [procedure] (file-lock/blocking PORT [START [LEN]])
725
726Similar to {{file-lock}}, but if a lock is held on the file,
727the current process blocks (including all threads) until the lock is released.
728
729==== file-test-lock
730
731 [procedure] (file-test-lock PORT [START [LEN]])
732
733Tests whether the file associated with {{PORT}} is locked for reading
734or writing (according to whether {{PORT}} is an input- or output-port)
735and returns either {{#f}} or the process-id of the locking process.
736
737==== file-unlock
738
739 [procedure] (file-unlock LOCK)
740
741Unlocks the previously locked portion of a file given in {{LOCK}}.
742
743
744=== Signal handling
745
746==== set-alarm!
747
748 [procedure] (set-alarm! SECONDS)
749
750Sets an internal timer to raise the {{signal/alrm}}
751after {{SECONDS}} are elapsed.  You can use the
752{{set-signal-handler!}} procedure to write a handler for this signal.
753
754==== set-signal-handler!
755
756 [procedure] (set-signal-handler! SIGNUM PROC)
757
758Establishes the procedure of one argument {{PROC}} as the handler
759for the signal with the code {{SIGNUM}}. {{PROC}} is called
760with the signal number as its sole argument. If the argument {{PROC}} is {{#f}}
761then any signal handler will be removed.
762
763Note that is is unspecified in which thread of execution the signal handler will be invoked.
764
765==== signal-handler
766
767 [procedure] (signal-handler SIGNUM)
768
769Returns the signal handler for the code {{SIGNUM}} or {{#f}}.
770
771==== set-signal-mask!
772
773 [procedure] (set-signal-mask! SIGLIST)
774
775Sets the signal mask of the current process to block all signals given
776in the list {{SIGLIST}}.  Signals masked in that way will not be
777delivered to the current process.
778
779==== signal-mask
780
781 [procedure] (signal-mask)
782
783Returns the signal mask of the current process.
784
785==== signal-masked?
786
787 [procedure] (signal-masked? SIGNUM)
788
789Returns whether the signal for the code {{SIGNUM}} is currently masked.
790
791==== signal-mask!
792
793 [procedure] (signal-mask! SIGNUM)
794
795Masks (blocks) the signal for the code {{SIGNUM}}.
796
797==== signal-unmask!
798
799 [procedure] (signal-unmask! SIGNUM)
800
801Unmasks (unblocks) the signal for the code {{SIGNUM}}.
802
803==== signal/term
804==== signal/kill
805==== signal/int
806==== signal/hup
807==== signal/fpe
808==== signal/ill
809==== signal/segv
810==== signal/abrt
811==== signal/trap
812==== signal/quit
813==== signal/alrm
814==== signal/vtalrm
815==== signal/prof
816==== signal/io
817==== signal/urg
818==== signal/chld
819==== signal/cont
820==== signal/stop
821==== signal/tstp
822==== signal/pipe
823==== signal/xcpu
824==== signal/xfsz
825==== signal/usr1
826==== signal/usr2
827==== signal/winch
828
829These variables contain signal codes for use with {{process-signal}},  {{set-signal-handler!}},  {{signal-handler}},  {{signal-masked?}},  {{signal-mask!}},  or {{signal-unmask!}}.
830
831
832=== Environment access
833
834==== current-environment
835
836 [procedure] (current-environment)
837
838Returns a association list of the environment variables and their
839current values.
840
841==== setenv
842
843 [procedure] (setenv VARIABLE VALUE)
844
845Sets the environment variable named {{VARIABLE}} to
846{{VALUE}}. Both arguments should be strings. If the variable is
847not defined in the environment, a new definition is created.
848
849==== unsetenv
850
851 [procedure] (unsetenv VARIABLE)
852
853Removes the definition of the environment variable {{VARIABLE}} from
854the environment of the current process. If the variable is not defined,
855nothing happens.
856
857
858=== Memory mapped I/O
859
860==== memory-mapped-file?
861
862 [pocedure] (memory-mapped-file? X)
863
864Returns {{#t}}, if {{X}} is an object representing a memory
865mapped file, or {{#f}} otherwise.
866
867==== map-file-to-memory
868
869 [procedure] (map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])
870
871Maps a section of a file to memory using the C function
872{{mmap()}}.  {{ADDRESS}} should be a foreign pointer object
873or {{#f}}; {{LEN}} specifies the size of the section to
874be mapped; {{PROTECTION}} should be one or more of the flags
875{{prot/read, prot/write, prot/exec}} or {{prot/none}}
876'''bitwise-ior'''ed together; {{FLAG}} should be one or more of
877the flags {{map/fixed, map/shared, map/private, map/anonymous}} or
878{{map/file}}; {{FILENO}} should be the file-descriptor of the
879mapped file. The optional argument {{OFFSET}} gives the offset of
880the section of the file to be mapped and defaults to 0. This procedure
881returns an object representing the mapped file section.  The procedure
882{{move-memory!}} can be used to access the mapped memory.
883
884==== memory-mapped-file-pointer
885
886 [procedure] (memory-mapped-file-pointer MMAP)
887
888Returns a machine pointer to the start of the memory region to which
889the file is mapped.
890
891==== unmap-file-from-memory
892
893 [procedure] (unmap-file-from-memory MMAP [LEN])
894
895Unmaps the section of a file mapped to memory using the C function
896{{munmap()}}.  {{MMAP}} should be a mapped file as returned
897by the procedure {{map-file-to-memory}}.  The optional argument
898{{LEN}} specifies the length of the section to be unmapped and
899defaults to the complete length given when the file was mapped.
900
901
902=== Date and time routines
903
904==== seconds->local-time
905
906 [procedure] (seconds->local-time SECONDS)
907
908Breaks down the time value represented in {{SECONDS}} into a 10
909element vector of the form {{#(seconds minutes hours mday month
910year wday yday dstflag timezone)}}, in the following format:
911
912; seconds (0) : the number of seconds after the minute (0 - 59)
913; minutes (1) : the number of minutes after the hour (0 - 59)
914; hours (2) : the number of hours past midnight (0 - 23)
915; mday (3) : the day of the month (1 - 31)
916; month (4) : the number of months since january (0 - 11)
917; year (5) : the number of years since 1900
918; wday (6) : the number of days since Sunday (0 - 6)
919; yday (7) : the number of days since January 1 (0 - 365)
920; dstflag (8) : a flag that is true if Daylight Saving Time is in effect at the time described.
921; timezone (9) : the difference between UTC and the latest local standard time, in seconds west of UTC.
922
923==== local-time->seconds
924
925 [procedure] (local-time->seconds VECTOR)
926
927Converts the ten-element vector {{VECTOR}} representing the time value relative to
928the current timezone into
929the number of seconds since the first of January, 1970 UTC.
930
931==== local-timezone-abbreviation
932
933 [procedure] (local-timezone-abbreviation)
934
935Returns the abbreviation for the local timezone as a string.
936
937==== seconds->string
938
939 [procedure] (seconds->string SECONDS)
940
941Converts the local time represented in {{SECONDS}} into a string
942of the form {{"Tue May 21 13:46:22 1991"}}.
943
944==== seconds->utc-time
945
946 [procedure] (seconds->utc-time SECONDS)
947
948Similar to {{seconds->local-time}}, but interpretes {{SECONDS}}
949as UTC time.
950
951==== utc-time->seconds
952
953 [procedure] (utc-time->seconds VECTOR)
954
955Converts the ten-element vector {{VECTOR}} representing the UTC time value into
956the number of seconds since the first of January, 1970 UTC.
957
958==== time->string
959
960 [procedure] (time->string VECTOR [FORMAT])
961
962Without a {{FORMAT}} string converts the broken out time represented in the 10
963element vector {{VECTOR}} into a string of the form {{"Tue May 21 13:46:22
9641991"}}.
965
966Otherwise returns the time as a string formatted per the {{FORMAT}} string.
967
968See the {{strftime}} C procedure for a specification of the {{FORMAT}} string.
969
970==== string->time
971
972 [procedure] (string->time STRING [FORMAT])
973
974Returns the time string parsed per the {{FORMAT}} string as a broken out time
97510 element vector.
976
977The default {{FORMAT}} string is {{"%a %b %e %H:%M:%S %Z %Y"}}. (The default
978{{date}} command format.)
979
980See the {{strptime}} C procedure for a specification of the {{FORMAT}} string.
981
982=== Raw exit
983
984==== _exit
985
986 [procedure] (_exit [CODE])
987
988Exits the current process without flushing any buffered output (using
989the C function {{_exit}}).  Note that the {{exit-handler}}
990is not called when this procedure is invoked. The optional return-code
991{{CODE}} defaults to {{0}}.
992
993
994=== ERRNO values
995
996==== errno/perm
997==== errno/noent
998==== errno/srch
999==== errno/intr
1000==== errno/io
1001==== errno/noexec
1002==== errno/badf
1003==== errno/child
1004==== errno/nomem
1005==== errno/acces
1006==== errno/fault
1007==== errno/busy
1008==== errno/notdir
1009==== errno/isdir
1010==== errno/inval
1011==== errno/mfile
1012==== errno/nospc
1013==== errno/spipe
1014==== errno/pipe
1015==== errno/again
1016==== errno/rofs
1017==== errno/exist
1018==== errno/wouldblock
1019These variables contain error codes as returned by {{errno}}.
1020
1021
1022=== Finding files
1023
1024==== find-files
1025
1026 [procedure] (find-files DIRECTORY PREDICATE [ACTION [IDENTITY [LIMIT]]])
1027
1028Recursively traverses the contents of {{DIRECTORY}} (which should
1029be a string) and invokes the procedure {{ACTION}} for all files
1030in which the procedure {{PREDICATE}} is true.  {{PREDICATE}}
1031may me a procedure of one argument or a regular-expression string.
1032{{ACTION}} should be a procedure of two arguments: the currently
1033encountered file and the result of the previous invocation of
1034{{ACTION}}, or, if this is the first invocation, the value
1035of {{IDENTITY}}. {{ACTION}} defaults to {{cons}},
1036{{IDENTITY}} defaults to {{()}}.  {{LIMIT}} should be a
1037procedure of one argument that is called for each nested directory
1038and which should return true, if that directory is to be traversed
1039recursively. {{LIMIT}} may also be an exact integer that
1040gives the maximum recursion depth. For example, a depth of {{0}} means that only files in the top-level, specified directory are to be traversed. In this case, all nested directories are ignored.  {{LIMIT}} may also be {{#f}} (the default),
1041which is equivalent to {{(constantly #t)}}.
1042
1043Note that {{ACTION}} is called with the full pathname of each file,
1044including the directory prefix.
1045
1046
1047=== Getting the hostname and system information
1048
1049==== get-host-name
1050
1051 [procedure] (get-host-name)
1052
1053Returns the hostname of the machine that this process is running on.
1054
1055==== system-information
1056
1057 [procedure] (system-information)
1058
1059Invokes the UNIX system call {{uname()}} and returns a list of 5 values:
1060system-name, node-name, OS release, OS version and machine.
1061
1062=== Setting the file buffering mode
1063
1064==== set-buffering-mode!
1065
1066 [procedure] (set-buffering-mode! PORT MODE [BUFSIZE])
1067
1068Sets the buffering-mode for the file associated with {{PORT}} to
1069{{MODE}}, which should be one of the keywords {{#:full}},
1070{{#:line}} or {{#:none}}. If {{BUFSIZE}} is specified it
1071determines the size of the buffer to be used (if any).
1072
1073
1074=== Terminal ports
1075
1076==== terminal-name
1077
1078 [procedure] (terminal-name PORT)
1079
1080Returns the name of the terminal that is connected to {{PORT}}.
1081
1082==== terminal-port?
1083
1084 [procedure] (terminal-port? PORT)
1085
1086Returns {{#t}} if {{PORT}} is connected to a terminal and
1087{{#f}} otherwise.
1088
1089==== terminal-size
1090
1091 [procedure] (terminal-size PORT)
1092
1093Returns two values: The height and width of the terminal connected to {{PORT}}.
1094
1095=== How Scheme procedures relate to UNIX C functions
1096
1097<table>
1098<tr><td> change-directory
1099chdir
1100</td></tr><tr><td> change-file-mode
1101chmod
1102</td></tr><tr><td> change-file-owner
1103chown
1104</td></tr><tr><td> create-directory
1105mkdir
1106</td></tr><tr><td> create-fifo
1107mkfifo
1108</td></tr><tr><td> create-pipe
1109pipe
1110</td></tr><tr><td> create-session
1111setsid
1112</td></tr><tr><td> create-symbolic-link
1113link
1114</td></tr><tr><td> current-directory
1115curdir
1116</td></tr><tr><td> current-effective-groupd-id
1117getegid
1118</td></tr><tr><td> current-effective-user-id
1119geteuid
1120</td></tr><tr><td> current-group-id
1121getgid
1122</td></tr><tr><td> current-parent-id
1123getppid
1124</td></tr><tr><td> current-process-id
1125getpid
1126</td></tr><tr><td> current-user-id
1127getuid
1128</td></tr><tr><td> delete-directory
1129rmdir
1130</td></tr><tr><td> duplicate-fileno
1131dup/dup2
1132</td></tr><tr><td> _exit
1133_exit
1134</td></tr><tr><td> file-close
1135close
1136</td></tr><tr><td> file-access-time
1137stat
1138</td></tr><tr><td> file-change-time
1139stat
1140</td></tr><tr><td> file-modification-time
1141stat
1142</td></tr><tr><td> file-execute-access?
1143access
1144</td></tr><tr><td> file-open
1145open
1146</td></tr><tr><td> file-lock
1147fcntl
1148</td></tr><tr><td> file-position
1149ftell/lseek
1150</td></tr><tr><td> file-read
1151read
1152</td></tr><tr><td> file-read-access?
1153access
1154</td></tr><tr><td> file-select
1155select
1156</td></tr><tr><td> file-control
1157fcntl
1158</td></tr><tr><td> file-stat
1159stat
1160</td></tr><tr><td> file-test-lock
1161fcntl
1162</td></tr><tr><td> file-truncate
1163truncate/ftruncate
1164</td></tr><tr><td> file-unlock
1165fcntl
1166</td></tr><tr><td> file-write
1167write
1168</td></tr><tr><td> file-write-access?
1169access
1170</td></tr><tr><td> get-groups
1171getgroups
1172</td></tr><tr><td> get-host-name
1173gethostname
1174</td></tr><tr><td> initialize-groups
1175initgroups
1176</td></tr><tr><td> local-time->seconds
1177mktime
1178</td></tr><tr><td> local-timezone-abbreviation
1179localtime
1180</td></tr><tr><td> map-file-to-memory
1181mmap
1182</td></tr><tr><td> open-input-file*
1183fdopen
1184</td></tr><tr><td> open-output-file*
1185fdopen
1186</td></tr><tr><td> open-input-pipe
1187popen
1188</td></tr><tr><td> open-output-pipe
1189popen
1190</td></tr><tr><td> port->fileno
1191fileno
1192</td></tr><tr><td> process-execute
1193execvp
1194</td></tr><tr><td> process-fork
1195fork
1196</td></tr><tr><td> process-group-id
1197getpgid
1198</td></tr><tr><td> process-signal
1199kill
1200</td></tr><tr><td> process-wait
1201waitpid
1202</td></tr><tr><td> close-input-pipe
1203pclose
1204</td></tr><tr><td> close-output-pipe
1205pclose
1206</td></tr><tr><td> read-symbolic-link
1207readlink
1208</td></tr><tr><td> seconds->local-time
1209localtime
1210</td></tr><tr><td> seconds->string
1211ctime
1212</td></tr><tr><td> seconds->utc-time
1213gmtime
1214</td></tr><tr><td> set-alarm!
1215alarm
1216</td></tr><tr><td> set-buffering-mode!
1217setvbuf
1218</td></tr><tr><td> set-file-position!
1219fseek/seek
1220</td></tr><tr><td> set-groups!
1221setgroups
1222</td></tr><tr><td> set-signal-mask!
1223sigprocmask
1224</td></tr><tr><td> set-group-id!
1225setgid
1226</td></tr><tr><td> set-process-group-id!
1227setpgid
1228</td></tr><tr><td> set-user-id!
1229setuid
1230</td></tr><tr><td> set-root-directory!
1231chroot
1232</td></tr><tr><td> setenv
1233setenv/putenv
1234</td></tr><tr><td> sleep
1235sleep
1236</td></tr><tr><td> system-information
1237uname
1238</td></tr><tr><td> terminal-name
1239ttyname
1240</td></tr><tr><td> terminal-port?
1241isatty
1242</td></tr><tr><td> time->string
1243asctime
1244</td></tr><tr><td> unsetenv
1245putenv
1246</td></tr><tr><td> unmap-file-from-memory
1247munmap
1248</td></tr><tr><td> user-information
1249getpwnam/getpwuid
1250</td></tr><tr><td> utc-time->seconds
1251timegm
1252</td></tr></table>
1253
1254
1255=== Windows specific notes
1256
1257Use of UTF8 encoded strings is for pathnames is not supported. Windows uses a
125816-bit UNICODE encoding with special system calls for wide-character support.
1259Only single-byte string encoding can be used.
1260
1261==== Procedure Changes
1262
1263Exceptions to the above procedure definitions.
1264
1265 [procedure] (create-pipe [MODE])
1266
1267The optional parameter {{MODE}}, default {{open/binary | open/noinherit}}. This can be {{open/binary}} or
1268{{open/text}}, optionally or'ed with {{open/noinherit}}.
1269
1270 [procedure] (process-wait [PID [NOHANG]])
1271
1272{{process-wait}} always returns {{#t}} for a terminated process and only the exit
1273status is available. (Windows does not provide signals as an interprocess
1274communication method.)
1275
1276 [procedure] (process-execute PATHNAME [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])
1277 [procedure] (process COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])
1278 [procedure] (process* COMMAND ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]])
1279
1280The optional parameter {{EXACT-FLAG}}, default {{#f}}. When {{#f}} any argument string with
1281embedded whitespace will be wrapped in quotes. When {{#t}} no such wrapping occurs.
1282
1283==== Unsupported Definitions
1284
1285The following definitions are not supported for native Windows builds (compiled with the
1286Microsoft tools or with MinGW):
1287
1288 open/noctty  open/nonblock  open/fsync  open/sync
1289 perm/isvtx  perm/isuid  perm/isgid
1290 file-select file-control
1291 signal/... (except signal/term, signal/int, signal/fpe, signal/ill, signal/segv, signal/abrt, signal/break)
1292 set-signal-mask!  signal-mask  signal-masked?  signal-mask!  signal-unmask!
1293 user-information  group-information  get-groups  set-groups!  initialize-groups
1294 errno/wouldblock
1295 change-file-owner
1296 current-user-id  current-group-id  current-effective-user-id  current-effective-groupd-id
1297 set-user-id!  set-group-id!
1298 create-session
1299 process-group-id  set-process-group-id!
1300 create-symbolic-link  read-symbolic-link
1301 file-truncate
1302 file-lock  file-lock/blocking  file-unlock  file-test-lock
1303 create-fifo  fifo?
1304 prot/...
1305 map/...
1306 map-file-to-memory  unmap-file-from-memory  memory-mapped-file-pointer  memory-mapped-file?
1307 set-alarm!
1308 terminal-port?  terminal-name terminal-size
1309 process-fork  process-signal
1310 parent-process-id
1311 set-root-directory!
1312 utc-time->seconds
1313 string->time
1314
1315==== Additional Definitions
1316
1317Only available for Windows
1318
1319* open/noinherit
1320
1321This variable is a mode value for {{create-pipe}}. Useful when spawning a child process.
1322
1323* spawn/overlay
1324* spawn/wait
1325* spawn/nowait
1326* spawn/nowaito
1327* spawn/detach
1328
1329These variables contains special flags that specify the exact semantics of {{process-spawn}}:
1330{{spawn/overlay}} replaces the current process with the new one.
1331{{spawn/wait}} suspends execution of the current process until the spawned process returns.
1332{{spawn/nowait}} does the opposite ({{spawn/nowaito}} is identical, according to the Microsoft
1333documentation) and runs the process asynchronously.
1334{{spawn/detach}} runs the new process in the background, without being attached to a console.
1335
1336==== process-spawn
1337
1338 [procedure] (process-spawn MODE COMMAND [ARGUMENT-LIST [ENVIRONMENT-LIST [EXACT-FLAG]]])
1339
1340Creates and runs a new process with the given {{COMMAND}} filename and the optional
1341{{ARGUMENT-LIST}} and {{ENVIRONMENT-LIST}}. {{MODE}} specifies how exactly the process
1342should be executed and must be one or more of the {{spawn/...}} flags defined above.
1343
1344The {{EXACT-FLAG}}, default {{#f}}, controls quote-wrapping of argument strings. When {{#t}}
1345quote-wrapping is not performed.
1346
1347Returns:
1348* the exit status when synchronous
1349* the PID when asynchronous
1350* -1 when failure
1351
1352
1353Previous: [[Unit srfi-18]]
1354
1355Next: [[Unit utils]]
Note: See TracBrowser for help on using the repository browser.