source: project/chicken/trunk/manual/Unit posix @ 9845

Last change on this file since 9845 was 9845, checked in by Kon Lovett, 11 years ago

Put the new items back. Where did they go?

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