source: project/wiki/man/4/Unit posix @ 15295

Last change on this file since 15295 was 15295, checked in by felix winkelmann, 12 years ago

merged with manual from release branch

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