1UnixLabels(3)                    OCaml library                   UnixLabels(3)
2
3
4

NAME

6       UnixLabels - Interface to the Unix system.
7

Module

9       Module   UnixLabels
10

Documentation

12       Module UnixLabels
13        : sig end
14
15
16       Interface  to  the  Unix system.  To use as replacement to default Unix
17       module, add module Unix = UnixLabels in your implementation.
18
19
20
21
22
23
24
25       === Error report ===
26
27
28       type error = Unix.error =
29        | E2BIG  (* Argument list too long
30        *)
31        | EACCES  (* Permission denied
32        *)
33        | EAGAIN  (* Resource temporarily unavailable; try again
34        *)
35        | EBADF  (* Bad file descriptor
36        *)
37        | EBUSY  (* Resource unavailable
38        *)
39        | ECHILD  (* No child process
40        *)
41        | EDEADLK  (* Resource deadlock would occur
42        *)
43        | EDOM  (* Domain error for math functions, etc.
44        *)
45        | EEXIST  (* File exists
46        *)
47        | EFAULT  (* Bad address
48        *)
49        | EFBIG  (* File too large
50        *)
51        | EINTR  (* Function interrupted by signal
52        *)
53        | EINVAL  (* Invalid argument
54        *)
55        | EIO  (* Hardware I/O error
56        *)
57        | EISDIR  (* Is a directory
58        *)
59        | EMFILE  (* Too many open files by the process
60        *)
61        | EMLINK  (* Too many links
62        *)
63        | ENAMETOOLONG  (* Filename too long
64        *)
65        | ENFILE  (* Too many open files in the system
66        *)
67        | ENODEV  (* No such device
68        *)
69        | ENOENT  (* No such file or directory
70        *)
71        | ENOEXEC  (* Not an executable file
72        *)
73        | ENOLCK  (* No locks available
74        *)
75        | ENOMEM  (* Not enough memory
76        *)
77        | ENOSPC  (* No space left on device
78        *)
79        | ENOSYS  (* Function not supported
80        *)
81        | ENOTDIR  (* Not a directory
82        *)
83        | ENOTEMPTY  (* Directory not empty
84        *)
85        | ENOTTY  (* Inappropriate I/O control operation
86        *)
87        | ENXIO  (* No such device or address
88        *)
89        | EPERM  (* Operation not permitted
90        *)
91        | EPIPE  (* Broken pipe
92        *)
93        | ERANGE  (* Result too large
94        *)
95        | EROFS  (* Read-only file system
96        *)
97        | ESPIPE  (* Invalid seek e.g. on a pipe
98        *)
99        | ESRCH  (* No such process
100        *)
101        | EXDEV  (* Invalid link
102        *)
103        | EWOULDBLOCK  (* Operation would block
104        *)
105        | EINPROGRESS  (* Operation now in progress
106        *)
107        | EALREADY  (* Operation already in progress
108        *)
109        | ENOTSOCK  (* Socket operation on non-socket
110        *)
111        | EDESTADDRREQ  (* Destination address required
112        *)
113        | EMSGSIZE  (* Message too long
114        *)
115        | EPROTOTYPE  (* Protocol wrong type for socket
116        *)
117        | ENOPROTOOPT  (* Protocol not available
118        *)
119        | EPROTONOSUPPORT  (* Protocol not supported
120        *)
121        | ESOCKTNOSUPPORT  (* Socket type not supported
122        *)
123        | EOPNOTSUPP  (* Operation not supported on socket
124        *)
125        | EPFNOSUPPORT  (* Protocol family not supported
126        *)
127        | EAFNOSUPPORT  (* Address family not supported by protocol family
128        *)
129        | EADDRINUSE  (* Address already in use
130        *)
131        | EADDRNOTAVAIL  (* Can't assign requested address
132        *)
133        | ENETDOWN  (* Network is down
134        *)
135        | ENETUNREACH  (* Network is unreachable
136        *)
137        | ENETRESET  (* Network dropped connection on reset
138        *)
139        | ECONNABORTED  (* Software caused connection abort
140        *)
141        | ECONNRESET  (* Connection reset by peer
142        *)
143        | ENOBUFS  (* No buffer space available
144        *)
145        | EISCONN  (* Socket is already connected
146        *)
147        | ENOTCONN  (* Socket is not connected
148        *)
149        | ESHUTDOWN  (* Can't send after socket shutdown
150        *)
151        | ETOOMANYREFS  (* Too many references: can't splice
152        *)
153        | ETIMEDOUT  (* Connection timed out
154        *)
155        | ECONNREFUSED  (* Connection refused
156        *)
157        | EHOSTDOWN  (* Host is down
158        *)
159        | EHOSTUNREACH  (* No route to host
160        *)
161        | ELOOP  (* Too many levels of symbolic links
162        *)
163        | EOVERFLOW  (* File size or position not representable
164        *)
165        | EUNKNOWNERR of int
166         (* Unknown error
167        *)
168
169
170       The type of error codes.  Errors defined  in  the  POSIX  standard  and
171       additional  errors from UNIX98 and BSD.  All other errors are mapped to
172       EUNKNOWNERR.
173
174
175
176       exception Unix_error of error * string * string
177
178
179       Raised by the system calls below when an  error  is  encountered.   The
180       first component is the error code; the second component is the function
181       name; the third component is the string parameter to the  function,  if
182       it has one, or the empty string otherwise.
183
184
185
186       val error_message : error -> string
187
188       Return a string describing the given error code.
189
190
191
192       val handle_unix_error : ('a -> 'b) -> 'a -> 'b
193
194
195       handle_unix_error  f  x  applies f to x and returns the result.  If the
196       exception Unix_error is raised, it  prints  a  message  describing  the
197       error and exits with code 2.
198
199
200
201
202       === Access to the process environment ===
203
204
205       val environment : unit -> string array
206
207       Return  the process environment, as an array of strings with the format
208       ``variable=value''.
209
210
211
212       val getenv : string -> string
213
214       Return the value associated to a variable in the  process  environment.
215       Raise  Not_found if the variable is unbound.  (This function is identi‐
216       cal to Sys.getenv .)
217
218
219
220       val unsafe_getenv : string -> string
221
222       Return the value associated to a variable in the process environment.
223
224       Unlike UnixLabels.getenv , this function returns the value even if  the
225       process  has  special  privileges.  It is considered unsafe because the
226       programmer of a setuid or setgid program must be careful to avoid using
227       maliciously  crafted  environment variables in the search path for exe‐
228       cutables, the locations for temporary files or logs, and the like.
229
230
231       Since 4.06.0
232
233
234       Raises Not_found if the variable is unbound.
235
236
237
238       val putenv : string -> string -> unit
239
240
241       Unix.putenv name value sets the value associated to a variable  in  the
242       process environment.  name is the name of the environment variable, and
243       value its new associated value.
244
245
246
247
248       === Process handling ===
249
250
251       type process_status = Unix.process_status =
252        | WEXITED of int
253         (* The process terminated normally by exit  ;  the  argument  is  the
254       return code.
255        *)
256        | WSIGNALED of int
257         (*  The  process  was  killed by a signal; the argument is the signal
258       number.
259        *)
260        | WSTOPPED of int
261         (* The process was stopped by a signal; the argument  is  the  signal
262       number.
263        *)
264
265
266       The  termination  status  of a process.  See module Sys for the defini‐
267       tions of the standard signal numbers.  Note that they are not the  num‐
268       bers used by the OS.
269
270
271       type wait_flag = Unix.wait_flag =
272        |  WNOHANG   (* do not block if no child has died yet, but immediately
273       return with a pid equal to 0.
274        *)
275        | WUNTRACED  (* report also the children that receive stop signals.
276        *)
277
278
279       Flags for UnixLabels.waitpid .
280
281
282
283       val execv : prog:string -> args:string array -> 'a
284
285
286       execv prog args execute the program in file prog , with  the  arguments
287       args  ,  and  the  current process environment.  These execv* functions
288       never return: on success, the current program is replaced  by  the  new
289       one; on failure, a UnixLabels.Unix_error exception is raised.
290
291
292
293       val execve : prog:string -> args:string array -> env:string array -> 'a
294
295       Same  as UnixLabels.execv , except that the third argument provides the
296       environment to the program executed.
297
298
299
300       val execvp : prog:string -> args:string array -> 'a
301
302       Same as UnixLabels.execv , except that the program is searched  in  the
303       path.
304
305
306
307       val  execvpe  : prog:string -> args:string array -> env:string array ->
308       'a
309
310       Same as UnixLabels.execve , except that the program is searched in  the
311       path.
312
313
314
315       val fork : unit -> int
316
317       Fork  a  new  process. The returned integer is 0 for the child process,
318       the pid of the child process for the parent process.
319
320
321
322       val wait : unit -> int * process_status
323
324       Wait until one of the children processes die, and return  its  pid  and
325       termination status.
326
327
328
329       val waitpid : mode:wait_flag list -> int -> int * process_status
330
331       Same  as UnixLabels.wait , but waits for the child process whose pid is
332       given.  A pid of -1 means wait for any child.  A pid of  0  means  wait
333       for  any child in the same process group as the current process.  Nega‐
334       tive pid arguments represent process groups.  The list of options indi‐
335       cates  whether  waitpid  should  return immediately without waiting, or
336       also report stopped children.
337
338
339
340       val system : string -> process_status
341
342       Execute the given command, wait until it  terminates,  and  return  its
343       termination  status. The string is interpreted by the shell /bin/sh and
344       therefore can contain redirections, quotes, variables, etc. The  result
345       WEXITED 127 indicates that the shell couldn't be executed.
346
347
348
349       val getpid : unit -> int
350
351       Return the pid of the process.
352
353
354
355       val getppid : unit -> int
356
357       Return the pid of the parent process.
358
359
360
361       val nice : int -> int
362
363       Change  the  process  priority.  The  integer  argument is added to the
364       ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
365       ties.) Return the new nice value.
366
367
368
369
370       === Basic file input/output ===
371
372
373       type file_descr = Unix.file_descr
374
375
376       The abstract type of file descriptors.
377
378
379
380       val stdin : file_descr
381
382       File descriptor for standard input.
383
384
385
386       val stdout : file_descr
387
388       File descriptor for standard output.
389
390
391
392       val stderr : file_descr
393
394       File descriptor for standard error.
395
396
397       type open_flag = Unix.open_flag =
398        | O_RDONLY  (* Open for reading
399        *)
400        | O_WRONLY  (* Open for writing
401        *)
402        | O_RDWR  (* Open for reading and writing
403        *)
404        | O_NONBLOCK  (* Open in non-blocking mode
405        *)
406        | O_APPEND  (* Open for append
407        *)
408        | O_CREAT  (* Create if nonexistent
409        *)
410        | O_TRUNC  (* Truncate to 0 length if existing
411        *)
412        | O_EXCL  (* Fail if existing
413        *)
414        | O_NOCTTY  (* Don't make this dev a controlling tty
415        *)
416        | O_DSYNC  (* Writes complete as `Synchronised I/O data integrity com‐
417       pletion'
418        *)
419        | O_SYNC  (* Writes complete as `Synchronised I/O file integrity  com‐
420       pletion'
421        *)
422        | O_RSYNC  (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
423        *)
424        |  O_SHARE_DELETE  (* Windows only: allow the file to be deleted while
425       still open
426        *)
427        | O_CLOEXEC  (* Set the close-on-exec flag on the descriptor  returned
428       by UnixLabels.openfile
429
430        *)
431        |  O_KEEPEXEC  (* Clear the close-on-exec flag.  This is currently the
432       default.
433        *)
434
435
436       The flags to UnixLabels.openfile .
437
438
439       type file_perm = int
440
441
442       The type of file access rights, e.g.  0o640 is read and write for user,
443       read for group, none for others
444
445
446
447       val  openfile  :  string  ->  mode:open_flag  list -> perm:file_perm ->
448       file_descr
449
450       Open the named file with the given flags. Third argument is the permis‐
451       sions to give to the file if it is created. Return a file descriptor on
452       the named file.
453
454
455
456       val close : file_descr -> unit
457
458       Close a file descriptor.
459
460
461
462       val read : file_descr -> buf:bytes -> pos:int -> len:int -> int
463
464
465       read fd buff ofs len reads len bytes from descriptor fd , storing  them
466       in  byte  sequence buff , starting at position ofs in buff . Return the
467       number of bytes actually read.
468
469
470
471       val write : file_descr -> buf:bytes -> pos:int -> len:int -> int
472
473
474       write fd buff ofs len writes len bytes to descriptor fd ,  taking  them
475       from byte sequence buff , starting at position ofs in buff . Return the
476       number of bytes actually written.  write repeats the writing  operation
477       until all bytes have been written or an error occurs.
478
479
480
481       val single_write : file_descr -> buf:bytes -> pos:int -> len:int -> int
482
483       Same  as  write  ,  but attempts to write only once.  Thus, if an error
484       occurs, single_write guarantees that no data has been written.
485
486
487
488       val write_substring : file_descr -> buf:string -> pos:int -> len:int ->
489       int
490
491       Same  as  write  ,  but  take  the data from a string instead of a byte
492       sequence.
493
494
495       Since 4.02.0
496
497
498
499       val single_write_substring : file_descr ->  buf:string  ->  pos:int  ->
500       len:int -> int
501
502       Same  as  single_write  ,  but take the data from a string instead of a
503       byte sequence.
504
505
506       Since 4.02.0
507
508
509
510
511       === Interfacing with the standard input/output library ===
512
513
514       val in_channel_of_descr : file_descr -> Pervasives.in_channel
515
516       Create an input channel reading from the given descriptor.  The channel
517       is  initially  in  binary mode; use set_binary_mode_in ic false if text
518       mode is desired.
519
520
521
522       val out_channel_of_descr : file_descr -> Pervasives.out_channel
523
524       Create an output channel writing on the given descriptor.  The  channel
525       is  initially  in binary mode; use set_binary_mode_out oc false if text
526       mode is desired.
527
528
529
530       val descr_of_in_channel : Pervasives.in_channel -> file_descr
531
532       Return the descriptor corresponding to an input channel.
533
534
535
536       val descr_of_out_channel : Pervasives.out_channel -> file_descr
537
538       Return the descriptor corresponding to an output channel.
539
540
541
542
543       === Seeking and truncating ===
544
545
546       type seek_command = Unix.seek_command =
547        | SEEK_SET  (* indicates positions relative to the  beginning  of  the
548       file
549        *)
550        | SEEK_CUR  (* indicates positions relative to the current position
551        *)
552        | SEEK_END  (* indicates positions relative to the end of the file
553        *)
554
555
556       Positioning modes for UnixLabels.lseek .
557
558
559
560       val lseek : file_descr -> int -> mode:seek_command -> int
561
562       Set  the current position for a file descriptor, and return the result‐
563       ing offset (from the beginning of the file).
564
565
566
567       val truncate : string -> len:int -> unit
568
569       Truncates the named file to the given size.
570
571
572
573       val ftruncate : file_descr -> len:int -> unit
574
575       Truncates the file corresponding to the given descriptor to  the  given
576       size.
577
578
579
580
581       === File status ===
582
583
584       type file_kind = Unix.file_kind =
585        | S_REG  (* Regular file
586        *)
587        | S_DIR  (* Directory
588        *)
589        | S_CHR  (* Character device
590        *)
591        | S_BLK  (* Block device
592        *)
593        | S_LNK  (* Symbolic link
594        *)
595        | S_FIFO  (* Named pipe
596        *)
597        | S_SOCK  (* Socket
598        *)
599
600
601
602
603       type stats = Unix.stats = {
604        st_dev : int ;  (* Device number
605        *)
606        st_ino : int ;  (* Inode number
607        *)
608        st_kind : file_kind ;  (* Kind of the file
609        *)
610        st_perm : file_perm ;  (* Access rights
611        *)
612        st_nlink : int ;  (* Number of links
613        *)
614        st_uid : int ;  (* User id of the owner
615        *)
616        st_gid : int ;  (* Group ID of the file's group
617        *)
618        st_rdev : int ;  (* Device minor number
619        *)
620        st_size : int ;  (* Size in bytes
621        *)
622        st_atime : float ;  (* Last access time
623        *)
624        st_mtime : float ;  (* Last modification time
625        *)
626        st_ctime : float ;  (* Last status change time
627        *)
628        }
629
630
631       The information returned by the UnixLabels.stat calls.
632
633
634
635       val stat : string -> stats
636
637       Return the information for the named file.
638
639
640
641       val lstat : string -> stats
642
643       Same  as  UnixLabels.stat  ,  but  in case the file is a symbolic link,
644       return the information for the link itself.
645
646
647
648       val fstat : file_descr -> stats
649
650       Return the information for the file associated with the given  descrip‐
651       tor.
652
653
654
655       val isatty : file_descr -> bool
656
657       Return  true  if the given file descriptor refers to a terminal or con‐
658       sole window, false otherwise.
659
660
661
662
663       === File operations on large files ===
664
665
666       module LargeFile : sig end
667
668
669       File operations on large files.  This sub-module provides 64-bit  vari‐
670       ants of the functions UnixLabels.lseek (for positioning a file descrip‐
671       tor), UnixLabels.truncate and UnixLabels.ftruncate  (for  changing  the
672       size  of  a  file),  and UnixLabels.stat , UnixLabels.lstat and UnixLa‐
673       bels.fstat (for obtaining information on files).  These alternate func‐
674       tions  represent  positions  and sizes by 64-bit integers (type int64 )
675       instead of regular integers (type int ),  thus  allowing  operating  on
676       files whose sizes are greater than max_int .
677
678
679
680
681       === Mapping files into memory ===
682
683
684       val  map_file : file_descr -> ?pos:int64 -> kind:('a, 'b) Bigarray.kind
685       -> layout:'c Bigarray.layout -> shared:bool -> dims:int array  ->  ('a,
686       'b, 'c) Bigarray.Genarray.t
687
688       Memory  mapping  of  a  file  as  a big array.  map_file fd kind layout
689       shared dims returns a big array of kind kind  ,  layout  layout  ,  and
690       dimensions as specified in dims .  The data contained in this big array
691       are the contents of the file referred to by the file descriptor fd  (as
692       opened  previously with Unix.openfile , for example).  The optional pos
693       parameter is the byte offset in the file of the data being  mapped;  it
694       defaults to 0 (map from the beginning of the file).
695
696       If  shared  is  true  ,  all  modifications  performed on the array are
697       reflected in the file.  This requires that fd be opened with write per‐
698       missions.   If  shared  is false , modifications performed on the array
699       are done in memory only, using copy-on-write of the modified pages; the
700       underlying file is not affected.
701
702
703       Genarray.map_file is much more efficient than reading the whole file in
704       a big array, modifying that big array, and writing it afterwards.
705
706       To adjust automatically the dimensions of the big array to  the  actual
707       size of the file, the major dimension (that is, the first dimension for
708       an array with C layout, and the last dimension for an array  with  For‐
709       tran  layout)  can  be given as -1 .  Genarray.map_file then determines
710       the major dimension from the size of the file.  The file  must  contain
711       an  integral number of sub-arrays as determined by the non-major dimen‐
712       sions, otherwise Failure is raised.
713
714       If all dimensions of the big array are given, the file size is  matched
715       against  the size of the big array.  If the file is larger than the big
716       array, only the initial portion of the file is mapped to the big array.
717       If  the  file  is smaller than the big array, the file is automatically
718       grown to the size of the big array.  This requires write permissions on
719       fd .
720
721       Array accesses are bounds-checked, but the bounds are determined by the
722       initial call to map_file . Therefore, you should  make  sure  no  other
723       process modifies the mapped file while you're accessing it, or a SIGBUS
724       signal may be raised. This  happens,  for  instance,  if  the  file  is
725       shrunk.
726
727
728       Invalid_argument or Failure may be raised in cases where argument vali‐
729       dation fails.
730
731
732       Since 4.06.0
733
734
735
736
737       === Operations on file names ===
738
739
740       val unlink : string -> unit
741
742       Removes the named file
743
744
745
746       val rename : src:string -> dst:string -> unit
747
748
749       rename old new changes the name of a file from old to new .
750
751
752
753       val link : src:string -> dst:string -> unit
754
755
756       link source dest creates a hard link  named  dest  to  the  file  named
757       source .
758
759
760
761
762       === File permissions and ownership ===
763
764
765       type access_permission = Unix.access_permission =
766        | R_OK  (* Read permission
767        *)
768        | W_OK  (* Write permission
769        *)
770        | X_OK  (* Execution permission
771        *)
772        | F_OK  (* File exists
773        *)
774
775
776       Flags for the UnixLabels.access call.
777
778
779
780       val chmod : string -> perm:file_perm -> unit
781
782       Change the permissions of the named file.
783
784
785
786       val fchmod : file_descr -> perm:file_perm -> unit
787
788       Change the permissions of an opened file.
789
790
791
792       val chown : string -> uid:int -> gid:int -> unit
793
794       Change the owner uid and owner gid of the named file.
795
796
797
798       val fchown : file_descr -> uid:int -> gid:int -> unit
799
800       Change the owner uid and owner gid of an opened file.
801
802
803
804       val umask : int -> int
805
806       Set  the  process's  file  mode  creation mask, and return the previous
807       mask.
808
809
810
811       val access : string -> perm:access_permission list -> unit
812
813       Check that the process has the given permissions over the  named  file.
814       Raise Unix_error otherwise.
815
816
817
818
819       === Operations on file descriptors ===
820
821
822       val dup : ?cloexec:bool -> file_descr -> file_descr
823
824       Return  a  new  file  descriptor referencing the same file as the given
825       descriptor.
826
827
828
829       val dup2 : ?cloexec:bool -> src:file_descr -> dst:file_descr -> unit
830
831
832       dup2 fd1 fd2 duplicates fd1 to fd2 , closing fd2 if already opened.
833
834
835
836       val set_nonblock : file_descr -> unit
837
838       Set the ``non-blocking''  flag  on  the  given  descriptor.   When  the
839       non-blocking  flag  is  set,  reading on a descriptor on which there is
840       temporarily no data available raises the EAGAIN  or  EWOULDBLOCK  error
841       instead  of  blocking; writing on a descriptor on which there is tempo‐
842       rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
843
844
845
846       val clear_nonblock : file_descr -> unit
847
848       Clear the ``non-blocking'' flag on the given descriptor.   See  UnixLa‐
849       bels.set_nonblock .
850
851
852
853       val set_close_on_exec : file_descr -> unit
854
855       Set  the  ``close-on-exec'' flag on the given descriptor.  A descriptor
856       with the close-on-exec flag is automatically closed  when  the  current
857       process starts another program with one of the exec functions.
858
859
860
861       val clear_close_on_exec : file_descr -> unit
862
863       Clear  the ``close-on-exec'' flag on the given descriptor.  See UnixLa‐
864       bels.set_close_on_exec .
865
866
867
868
869       === Directories ===
870
871
872       val mkdir : string -> perm:file_perm -> unit
873
874       Create a directory with the given permissions.
875
876
877
878       val rmdir : string -> unit
879
880       Remove an empty directory.
881
882
883
884       val chdir : string -> unit
885
886       Change the process working directory.
887
888
889
890       val getcwd : unit -> string
891
892       Return the name of the current working directory.
893
894
895
896       val chroot : string -> unit
897
898       Change the process root directory.
899
900
901       type dir_handle = Unix.dir_handle
902
903
904       The type of descriptors over opened directories.
905
906
907
908       val opendir : string -> dir_handle
909
910       Open a descriptor on a directory
911
912
913
914       val readdir : dir_handle -> string
915
916       Return the next entry in a directory.
917
918
919       Raises End_of_file when the end of the directory has been reached.
920
921
922
923       val rewinddir : dir_handle -> unit
924
925       Reposition the descriptor to the beginning of the directory
926
927
928
929       val closedir : dir_handle -> unit
930
931       Close a directory descriptor.
932
933
934
935
936       === Pipes and redirections ===
937
938
939       val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
940
941       Create a pipe. The first component of the result is opened for reading,
942       that's  the  exit to the pipe. The second component is opened for writ‐
943       ing, that's the entrance to the pipe.
944
945
946
947       val mkfifo : string -> perm:file_perm -> unit
948
949       Create a named pipe with the given permissions.
950
951
952
953
954       === High-level process and redirection management ===
955
956
957       val   create_process   :   prog:string   ->   args:string   array    ->
958       stdin:file_descr -> stdout:file_descr -> stderr:file_descr -> int
959
960
961       create_process  prog  args  new_stdin new_stdout new_stderr forks a new
962       process that executes the program in file prog , with arguments args  .
963       The  pid  of  the  new process is returned immediately; the new process
964       executes concurrently with the current process.  The standard input and
965       outputs of the new process are connected to the descriptors new_stdin ,
966       new_stdout and new_stderr .  Passing e.g.  stdout for  new_stdout  pre‐
967       vents the redirection and causes the new process to have the same stan‐
968       dard output as the  current  process.   The  executable  file  prog  is
969       searched  in the path.  The new process has the same environment as the
970       current process.
971
972
973
974       val create_process_env : prog:string -> args:string array -> env:string
975       array  -> stdin:file_descr -> stdout:file_descr -> stderr:file_descr ->
976       int
977
978
979       create_process_env prog args env new_stdin new_stdout new_stderr  works
980       as UnixLabels.create_process , except that the extra argument env spec‐
981       ifies the environment passed to the program.
982
983
984
985       val open_process_in : string -> Pervasives.in_channel
986
987       High-level pipe and process management. This function  runs  the  given
988       command  in parallel with the program.  The standard output of the com‐
989       mand is redirected to a pipe, which can be read via the returned  input
990       channel.   The command is interpreted by the shell /bin/sh (cf.  system
991       ).
992
993
994
995       val open_process_out : string -> Pervasives.out_channel
996
997       Same as UnixLabels.open_process_in , but redirect the standard input of
998       the  command to a pipe.  Data written to the returned output channel is
999       sent to the standard input of the command.  Warning: writes  on  output
1000       channels are buffered, hence be careful to call Pervasives.flush at the
1001       right times to ensure correct synchronization.
1002
1003
1004
1005       val  open_process  :   string   ->   Pervasives.in_channel   *   Perva‐
1006       sives.out_channel
1007
1008       Same  as  UnixLabels.open_process_out , but redirects both the standard
1009       input and standard output of the command to pipes connected to the  two
1010       returned channels.  The input channel is connected to the output of the
1011       command, and the output channel to the input of the command.
1012
1013
1014
1015       val  open_process_full  :  string  ->  env:string   array   ->   Perva‐
1016       sives.in_channel * Pervasives.out_channel * Pervasives.in_channel
1017
1018       Similar  to UnixLabels.open_process , but the second argument specifies
1019       the environment passed to the command.  The result is a triple of chan‐
1020       nels connected respectively to the standard output, standard input, and
1021       standard error of the command.
1022
1023
1024
1025       val close_process_in : Pervasives.in_channel -> process_status
1026
1027       Close channels opened by  UnixLabels.open_process_in  ,  wait  for  the
1028       associated command to terminate, and return its termination status.
1029
1030
1031
1032       val close_process_out : Pervasives.out_channel -> process_status
1033
1034       Close  channels  opened  by  UnixLabels.open_process_out , wait for the
1035       associated command to terminate, and return its termination status.
1036
1037
1038
1039       val close_process : Pervasives.in_channel *  Pervasives.out_channel  ->
1040       process_status
1041
1042       Close channels opened by UnixLabels.open_process , wait for the associ‐
1043       ated command to terminate, and return its termination status.
1044
1045
1046
1047       val close_process_full : Pervasives.in_channel * Pervasives.out_channel
1048       * Pervasives.in_channel -> process_status
1049
1050       Close  channels  opened  by UnixLabels.open_process_full , wait for the
1051       associated command to terminate, and return its termination status.
1052
1053
1054
1055
1056       === Symbolic links ===
1057
1058
1059       val symlink : ?to_dir:bool -> src:string -> dst:string -> unit
1060
1061
1062       symlink source dest creates the file dest as a  symbolic  link  to  the
1063       file source . See Unix.symlink for details of ~to_dir
1064
1065
1066
1067
1068       val has_symlink : unit -> bool
1069
1070       Returns  true if the user is able to create symbolic links. On Windows,
1071       this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1072       ilege  but  is also running elevated, if necessary. On other platforms,
1073       this is simply indicates that the symlink system call is available.
1074
1075
1076       Since 4.03.0
1077
1078
1079
1080       val readlink : string -> string
1081
1082       Read the contents of a link.
1083
1084
1085
1086
1087       === Polling ===
1088
1089
1090       val  select  :  read:file_descr  list  ->  write:file_descr   list   ->
1091       except:file_descr list -> timeout:float -> file_descr list * file_descr
1092       list * file_descr list
1093
1094       Wait until some input/output operations become possible on  some  chan‐
1095       nels.  The three list arguments are, respectively, a set of descriptors
1096       to check for reading (first argument), for writing  (second  argument),
1097       or for exceptional conditions (third argument).  The fourth argument is
1098       the maximal timeout, in seconds; a negative fourth  argument  means  no
1099       timeout  (unbounded  wait).   The  result  is composed of three sets of
1100       descriptors: those ready for reading (first component), ready for writ‐
1101       ing  (second  component),  and  over  which an exceptional condition is
1102       pending (third component).
1103
1104
1105
1106
1107       === Locking ===
1108
1109
1110       type lock_command = Unix.lock_command =
1111        | F_ULOCK  (* Unlock a region
1112        *)
1113        | F_LOCK  (* Lock a region for writing, and block if already locked
1114        *)
1115        | F_TLOCK  (* Lock a region for writing, or fail if already locked
1116        *)
1117        | F_TEST  (* Test a region for other process locks
1118        *)
1119        | F_RLOCK  (* Lock a region for reading, and block if already locked
1120        *)
1121        | F_TRLOCK  (* Lock a region for reading, or fail if already locked
1122        *)
1123
1124
1125       Commands for UnixLabels.lockf .
1126
1127
1128
1129       val lockf : file_descr -> mode:lock_command -> len:int -> unit
1130
1131
1132       lockf fd cmd size puts a lock on a region of the file opened  as  fd  .
1133       The  region starts at the current read/write position for fd (as set by
1134       UnixLabels.lseek ), and extends size bytes forward if size is positive,
1135       size  bytes backwards if size is negative, or to the end of the file if
1136       size is zero.  A write lock prevents any other process from acquiring a
1137       read  or  write  lock  on  the  region.  A read lock prevents any other
1138       process from acquiring a write lock on the region, but lets other  pro‐
1139       cesses acquire read locks on it.
1140
1141       The  F_LOCK  and  F_TLOCK  commands attempts to put a write lock on the
1142       specified region.  The F_RLOCK and F_TRLOCK commands attempts to put  a
1143       read  lock  on  the  specified  region.  If one or several locks put by
1144       another process prevent the current process from  acquiring  the  lock,
1145       F_LOCK  and  F_RLOCK block until these locks are removed, while F_TLOCK
1146       and F_TRLOCK fail immediately with an exception.  The  F_ULOCK  removes
1147       whatever  locks  the  current  process  has  on  the  specified region.
1148       Finally, the F_TEST command tests whether a write lock can be  acquired
1149       on  the  specified region, without actually putting a lock.  It returns
1150       immediately if successful, or fails otherwise.
1151
1152
1153
1154
1155       === Signals Note: installation of signal handlers is performed via  the
1156       functions Sys.signal and Sys.set_signal. ===
1157
1158
1159       val kill : pid:int -> signal:int -> unit
1160
1161
1162       kill pid sig sends signal number sig to the process with id pid .
1163
1164
1165       type sigprocmask_command = Unix.sigprocmask_command =
1166        | SIG_SETMASK
1167        | SIG_BLOCK
1168        | SIG_UNBLOCK
1169
1170
1171
1172
1173
1174       val sigprocmask : mode:sigprocmask_command -> int list -> int list
1175
1176
1177       sigprocmask  cmd  sigs  changes  the set of blocked signals.  If cmd is
1178       SIG_SETMASK , blocked signals are set to those in the list sigs  .   If
1179       cmd  is SIG_BLOCK , the signals in sigs are added to the set of blocked
1180       signals.  If cmd is SIG_UNBLOCK , the signals in sigs are removed  from
1181       the  set of blocked signals.  sigprocmask returns the set of previously
1182       blocked signals.
1183
1184
1185
1186       val sigpending : unit -> int list
1187
1188       Return the set of blocked signals that are currently pending.
1189
1190
1191
1192       val sigsuspend : int list -> unit
1193
1194
1195       sigsuspend sigs atomically sets the blocked signals to sigs  and  waits
1196       for  a non-ignored, non-blocked signal to be delivered.  On return, the
1197       blocked signals are reset to their initial value.
1198
1199
1200
1201       val pause : unit -> unit
1202
1203       Wait until a non-ignored, non-blocked signal is delivered.
1204
1205
1206
1207
1208       === Time functions ===
1209
1210
1211       type process_times = Unix.process_times = {
1212        tms_utime : float ;  (* User time for the process
1213        *)
1214        tms_stime : float ;  (* System time for the process
1215        *)
1216        tms_cutime : float ;  (* User time for the children processes
1217        *)
1218        tms_cstime : float ;  (* System time for the children processes
1219        *)
1220        }
1221
1222
1223       The execution times (CPU times) of a process.
1224
1225
1226       type tm = Unix.tm = {
1227        tm_sec : int ;  (* Seconds 0..60
1228        *)
1229        tm_min : int ;  (* Minutes 0..59
1230        *)
1231        tm_hour : int ;  (* Hours 0..23
1232        *)
1233        tm_mday : int ;  (* Day of month 1..31
1234        *)
1235        tm_mon : int ;  (* Month of year 0..11
1236        *)
1237        tm_year : int ;  (* Year - 1900
1238        *)
1239        tm_wday : int ;  (* Day of week (Sunday is 0)
1240        *)
1241        tm_yday : int ;  (* Day of year 0..365
1242        *)
1243        tm_isdst : bool ;  (* Daylight time savings in effect
1244        *)
1245        }
1246
1247
1248       The type representing wallclock time and calendar date.
1249
1250
1251
1252       val time : unit -> float
1253
1254       Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1255
1256
1257
1258       val gettimeofday : unit -> float
1259
1260       Same as UnixLabels.time , but with resolution better than 1 second.
1261
1262
1263
1264       val gmtime : float -> tm
1265
1266       Convert a time in seconds, as returned by UnixLabels.time , into a date
1267       and  a  time.  Assumes  UTC (Coordinated Universal Time), also known as
1268       GMT.
1269
1270
1271
1272       val localtime : float -> tm
1273
1274       Convert a time in seconds, as returned by UnixLabels.time , into a date
1275       and a time. Assumes the local time zone.
1276
1277
1278
1279       val mktime : tm -> float * tm
1280
1281       Convert  a  date and time, specified by the tm argument, into a time in
1282       seconds, as returned by UnixLabels.time .  The tm_isdst ,  tm_wday  and
1283       tm_yday fields of tm are ignored.  Also return a normalized copy of the
1284       given tm record, with the tm_wday  ,  tm_yday  ,  and  tm_isdst  fields
1285       recomputed  from  the other fields, and the other fields normalized (so
1286       that, e.g., 40 October is changed into 9 November).  The tm argument is
1287       interpreted in the local time zone.
1288
1289
1290
1291       val alarm : int -> int
1292
1293       Schedule a SIGALRM signal after the given number of seconds.
1294
1295
1296
1297       val sleep : int -> unit
1298
1299       Stop execution for the given number of seconds.
1300
1301
1302
1303       val times : unit -> process_times
1304
1305       Return the execution times of the process.
1306
1307
1308
1309       val utimes : string -> access:float -> modif:float -> unit
1310
1311       Set the last access time (second arg) and last modification time (third
1312       arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1313       1, 1970.  A time of 0.0 is interpreted as the current time.
1314
1315
1316       type interval_timer = Unix.interval_timer =
1317        |  ITIMER_REAL   (*  decrements  in  real  time,  and sends the signal
1318       SIGALRM when expired.
1319        *)
1320        | ITIMER_VIRTUAL  (* decrements in process  virtual  time,  and  sends
1321       SIGVTALRM when expired.
1322        *)
1323        |  ITIMER_PROF  (* (for profiling) decrements both when the process is
1324       running and when the system is running on behalf  of  the  process;  it
1325       sends SIGPROF when expired.
1326        *)
1327
1328
1329       The three kinds of interval timers.
1330
1331
1332       type interval_timer_status = Unix.interval_timer_status = {
1333        it_interval : float ;  (* Period
1334        *)
1335        it_value : float ;  (* Current value of the timer
1336        *)
1337        }
1338
1339
1340       The type describing the status of an interval timer
1341
1342
1343
1344       val getitimer : interval_timer -> interval_timer_status
1345
1346       Return the current status of the given interval timer.
1347
1348
1349
1350       val  setitimer  :  interval_timer  ->  interval_timer_status  -> inter‐
1351       val_timer_status
1352
1353
1354       setitimer t s sets the interval timer t and returns its  previous  sta‐
1355       tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1356       is the time to the next timer expiration; s.it_interval ,  if  nonzero,
1357       specifies  a  value  to  be  used  in reloading it_value when the timer
1358       expires.  Setting  s.it_value  to  zero  disable  the  timer.   Setting
1359       s.it_interval  to  zero  causes the timer to be disabled after its next
1360       expiration.
1361
1362
1363
1364
1365       === User id, group id ===
1366
1367
1368       val getuid : unit -> int
1369
1370       Return the user id of the user executing the process.
1371
1372
1373
1374       val geteuid : unit -> int
1375
1376       Return the effective user id under which the process runs.
1377
1378
1379
1380       val setuid : int -> unit
1381
1382       Set the real user id and effective user id for the process.
1383
1384
1385
1386       val getgid : unit -> int
1387
1388       Return the group id of the user executing the process.
1389
1390
1391
1392       val getegid : unit -> int
1393
1394       Return the effective group id under which the process runs.
1395
1396
1397
1398       val setgid : int -> unit
1399
1400       Set the real group id and effective group id for the process.
1401
1402
1403
1404       val getgroups : unit -> int array
1405
1406       Return the list of groups to  which  the  user  executing  the  process
1407       belongs.
1408
1409
1410
1411       val setgroups : int array -> unit
1412
1413
1414       setgroups  groups  sets  the  supplementary  group  IDs for the calling
1415       process. Appropriate privileges are required.
1416
1417
1418
1419       val initgroups : string -> int -> unit
1420
1421
1422       initgroups user group initializes the group access list by reading  the
1423       group  database /etc/group and using all groups of which user is a mem‐
1424       ber. The additional group group is also added to the list.
1425
1426
1427       type passwd_entry = Unix.passwd_entry = {
1428        pw_name : string ;
1429        pw_passwd : string ;
1430        pw_uid : int ;
1431        pw_gid : int ;
1432        pw_gecos : string ;
1433        pw_dir : string ;
1434        pw_shell : string ;
1435        }
1436
1437
1438       Structure of entries in the passwd database.
1439
1440
1441       type group_entry = Unix.group_entry = {
1442        gr_name : string ;
1443        gr_passwd : string ;
1444        gr_gid : int ;
1445        gr_mem : string array ;
1446        }
1447
1448
1449       Structure of entries in the groups database.
1450
1451
1452
1453       val getlogin : unit -> string
1454
1455       Return the login name of the user executing the process.
1456
1457
1458
1459       val getpwnam : string -> passwd_entry
1460
1461       Find an entry in passwd with the given name, or raise Not_found if  the
1462       matching entry is not found.
1463
1464
1465
1466       val getgrnam : string -> group_entry
1467
1468       Find  an  entry in group with the given name, or raise Not_found if the
1469       matching entry is not found.
1470
1471
1472
1473       val getpwuid : int -> passwd_entry
1474
1475       Find an entry in passwd with the given user id, or raise  Not_found  if
1476       the matching entry is not found.
1477
1478
1479
1480       val getgrgid : int -> group_entry
1481
1482       Find  an  entry in group with the given group id, or raise Not_found if
1483       the matching entry is not found.
1484
1485
1486
1487
1488       === Internet addresses ===
1489
1490
1491       type inet_addr = Unix.inet_addr
1492
1493
1494       The abstract type of Internet addresses.
1495
1496
1497
1498       val inet_addr_of_string : string -> inet_addr
1499
1500       Conversion from the printable representation of an Internet address  to
1501       its internal representation.  The argument string consists of 4 numbers
1502       separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up  to
1503       8  numbers  separated by colons for IPv6 addresses.  Raise Failure when
1504       given a string that does not match these formats.
1505
1506
1507
1508       val string_of_inet_addr : inet_addr -> string
1509
1510       Return the printable representation of the given Internet address.  See
1511       Unix.inet_addr_of_string for a description of the printable representa‐
1512       tion.
1513
1514
1515
1516       val inet_addr_any : inet_addr
1517
1518       A special IPv4 address, for use only with bind , representing  all  the
1519       Internet addresses that the host machine possesses.
1520
1521
1522
1523       val inet_addr_loopback : inet_addr
1524
1525       A special IPv4 address representing the host machine ( 127.0.0.1 ).
1526
1527
1528
1529       val inet6_addr_any : inet_addr
1530
1531       A  special  IPv6 address, for use only with bind , representing all the
1532       Internet addresses that the host machine possesses.
1533
1534
1535
1536       val inet6_addr_loopback : inet_addr
1537
1538       A special IPv6 address representing the host machine ( ::1 ).
1539
1540
1541
1542
1543       === Sockets ===
1544
1545
1546       type socket_domain = Unix.socket_domain =
1547        | PF_UNIX  (* Unix domain
1548        *)
1549        | PF_INET  (* Internet domain (IPv4)
1550        *)
1551        | PF_INET6  (* Internet domain (IPv6)
1552        *)
1553
1554
1555       The type of socket domains.  Not all  platforms  support  IPv6  sockets
1556       (type PF_INET6 ).
1557
1558
1559       type socket_type = Unix.socket_type =
1560        | SOCK_STREAM  (* Stream socket
1561        *)
1562        | SOCK_DGRAM  (* Datagram socket
1563        *)
1564        | SOCK_RAW  (* Raw socket
1565        *)
1566        | SOCK_SEQPACKET  (* Sequenced packets socket
1567        *)
1568
1569
1570       The type of socket kinds, specifying the semantics of communications.
1571
1572
1573       type sockaddr = Unix.sockaddr =
1574        | ADDR_UNIX of string
1575        | ADDR_INET of inet_addr * int
1576         (*  The type of socket addresses.  ADDR_UNIX name is a socket address
1577       in  the  Unix  domain;  name  is  a  file  name  in  the  file  system.
1578       ADDR_INET(addr,port)  is  a socket address in the Internet domain; addr
1579       is the Internet address of the machine, and port is the port number.
1580        *)
1581
1582
1583
1584
1585
1586       val socket : ?cloexec:bool -> domain:socket_domain ->  kind:socket_type
1587       -> protocol:int -> file_descr
1588
1589       Create  a  new socket in the given domain, and with the given kind. The
1590       third argument is the protocol type; 0 selects the default protocol for
1591       that kind of sockets.
1592
1593
1594
1595       val domain_of_sockaddr : sockaddr -> socket_domain
1596
1597       Return the socket domain adequate for the given socket address.
1598
1599
1600
1601       val    socketpair    :   ?cloexec:bool   ->   domain:socket_domain   ->
1602       kind:socket_type -> protocol:int -> file_descr * file_descr
1603
1604       Create a pair of unnamed sockets, connected together.
1605
1606
1607
1608       val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
1609
1610       Accept connections on the given socket. The returned  descriptor  is  a
1611       socket  connected to the client; the returned address is the address of
1612       the connecting client.
1613
1614
1615
1616       val bind : file_descr -> addr:sockaddr -> unit
1617
1618       Bind a socket to an address.
1619
1620
1621
1622       val connect : file_descr -> addr:sockaddr -> unit
1623
1624       Connect a socket to an address.
1625
1626
1627
1628       val listen : file_descr -> max:int -> unit
1629
1630       Set up a socket for receiving connection requests. The integer argument
1631       is the maximal number of pending requests.
1632
1633
1634       type shutdown_command = Unix.shutdown_command =
1635        | SHUTDOWN_RECEIVE  (* Close for receiving
1636        *)
1637        | SHUTDOWN_SEND  (* Close for sending
1638        *)
1639        | SHUTDOWN_ALL  (* Close both
1640        *)
1641
1642
1643       The type of commands for shutdown .
1644
1645
1646
1647       val shutdown : file_descr -> mode:shutdown_command -> unit
1648
1649       Shutdown  a socket connection.  SHUTDOWN_SEND as second argument causes
1650       reads on the other end of the connection to return an end-of-file  con‐
1651       dition.  SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
1652       tion to return a closed pipe condition ( SIGPIPE signal).
1653
1654
1655
1656       val getsockname : file_descr -> sockaddr
1657
1658       Return the address of the given socket.
1659
1660
1661
1662       val getpeername : file_descr -> sockaddr
1663
1664       Return the address of the host connected to the given socket.
1665
1666
1667       type msg_flag = Unix.msg_flag =
1668        | MSG_OOB
1669        | MSG_DONTROUTE
1670        | MSG_PEEK  (* The flags for UnixLabels.recv ,  UnixLabels.recvfrom  ,
1671       UnixLabels.send and UnixLabels.sendto .
1672        *)
1673
1674
1675
1676
1677
1678       val   recv   :  file_descr  ->  buf:bytes  ->  pos:int  ->  len:int  ->
1679       mode:msg_flag list -> int
1680
1681       Receive data from a connected socket.
1682
1683
1684
1685       val recvfrom :  file_descr  ->  buf:bytes  ->  pos:int  ->  len:int  ->
1686       mode:msg_flag list -> int * sockaddr
1687
1688       Receive data from an unconnected socket.
1689
1690
1691
1692       val   send   :  file_descr  ->  buf:bytes  ->  pos:int  ->  len:int  ->
1693       mode:msg_flag list -> int
1694
1695       Send data over a connected socket.
1696
1697
1698
1699       val send_substring : file_descr -> buf:string -> pos:int -> len:int  ->
1700       mode:msg_flag list -> int
1701
1702       Same  as  send  ,  but  take  the  data from a string instead of a byte
1703       sequence.
1704
1705
1706       Since 4.02.0
1707
1708
1709
1710       val  sendto  :  file_descr  ->  buf:bytes  ->  pos:int  ->  len:int  ->
1711       mode:msg_flag list -> addr:sockaddr -> int
1712
1713       Send data over an unconnected socket.
1714
1715
1716
1717       val  sendto_substring  : file_descr -> buf:string -> pos:int -> len:int
1718       -> mode:msg_flag list -> sockaddr -> int
1719
1720       Same as sendto , but take the data from a  string  instead  of  a  byte
1721       sequence.
1722
1723
1724       Since 4.02.0
1725
1726
1727
1728
1729       === Socket options ===
1730
1731
1732       type socket_bool_option =
1733        | SO_DEBUG  (* Record debugging information
1734        *)
1735        | SO_BROADCAST  (* Permit sending of broadcast messages
1736        *)
1737        | SO_REUSEADDR  (* Allow reuse of local addresses for bind
1738        *)
1739        | SO_KEEPALIVE  (* Keep connection active
1740        *)
1741        | SO_DONTROUTE  (* Bypass the standard routing algorithms
1742        *)
1743        | SO_OOBINLINE  (* Leave out-of-band data in line
1744        *)
1745        | SO_ACCEPTCONN  (* Report whether socket listening is enabled
1746        *)
1747        | TCP_NODELAY  (* Control the Nagle algorithm for TCP sockets
1748        *)
1749        | IPV6_ONLY  (* Forbid binding an IPv6 socket to an IPv4 address
1750        *)
1751
1752
1753       The socket options that can be consulted with UnixLabels.getsockopt and
1754       modified with UnixLabels.setsockopt .  These options have a  boolean  (
1755       true / false ) value.
1756
1757
1758       type socket_int_option =
1759        | SO_SNDBUF  (* Size of send buffer
1760        *)
1761        | SO_RCVBUF  (* Size of received buffer
1762        *)
1763        | SO_ERROR  (* Deprecated.  Use Unix.getsockopt_error instead.
1764        *)
1765        | SO_TYPE  (* Report the socket type
1766        *)
1767        |  SO_RCVLOWAT  (* Minimum number of bytes to process for input opera‐
1768       tions
1769        *)
1770        | SO_SNDLOWAT  (* Minimum number of bytes to process for output opera‐
1771       tions
1772        *)
1773
1774
1775       The socket options that can be consulted with UnixLabels.getsockopt_int
1776       and modified with UnixLabels.setsockopt_int .  These  options  have  an
1777       integer value.
1778
1779
1780       type socket_optint_option =
1781        | SO_LINGER  (* Whether to linger on closed connections that have data
1782       present, and for how long (in seconds)
1783        *)
1784
1785
1786       The socket options that can be  consulted  with  Unix.getsockopt_optint
1787       and  modified with Unix.setsockopt_optint .  These options have a value
1788       of type int option , with None meaning ``disabled''.
1789
1790
1791       type socket_float_option =
1792        | SO_RCVTIMEO  (* Timeout for input operations
1793        *)
1794        | SO_SNDTIMEO  (* Timeout for output operations
1795        *)
1796
1797
1798       The socket options  that  can  be  consulted  with  UnixLabels.getsock‐
1799       opt_float   and  modified  with  UnixLabels.setsockopt_float  .   These
1800       options have a floating-point value representing  a  time  in  seconds.
1801       The value 0 means infinite timeout.
1802
1803
1804
1805       val getsockopt : file_descr -> socket_bool_option -> bool
1806
1807       Return  the  current  status  of  a  boolean-valued option in the given
1808       socket.
1809
1810
1811
1812       val setsockopt : file_descr -> socket_bool_option -> bool -> unit
1813
1814       Set or clear a boolean-valued option in the given socket.
1815
1816
1817
1818       val getsockopt_int : file_descr -> socket_int_option -> int
1819
1820       Same as Unix.getsockopt for an integer-valued socket option.
1821
1822
1823
1824       val setsockopt_int : file_descr -> socket_int_option -> int -> unit
1825
1826       Same as Unix.setsockopt for an integer-valued socket option.
1827
1828
1829
1830       val getsockopt_optint  :  file_descr  ->  socket_optint_option  ->  int
1831       option
1832
1833       Same  as  Unix.getsockopt  for  a  socket  option whose value is an int
1834       option .
1835
1836
1837
1838       val setsockopt_optint  :  file_descr  ->  socket_optint_option  ->  int
1839       option -> unit
1840
1841       Same  as  Unix.setsockopt  for  a  socket  option whose value is an int
1842       option .
1843
1844
1845
1846       val getsockopt_float : file_descr -> socket_float_option -> float
1847
1848       Same as Unix.getsockopt for a socket option whose  value  is  a  float‐
1849       ing-point number.
1850
1851
1852
1853       val  setsockopt_float  :  file_descr -> socket_float_option -> float ->
1854       unit
1855
1856       Same as Unix.setsockopt for a socket option whose  value  is  a  float‐
1857       ing-point number.
1858
1859
1860
1861       val getsockopt_error : file_descr -> error option
1862
1863       Return  the error condition associated with the given socket, and clear
1864       it.
1865
1866
1867
1868
1869       === High-level network connection functions ===
1870
1871
1872       val  open_connection  :  sockaddr  ->  Pervasives.in_channel  *  Perva‐
1873       sives.out_channel
1874
1875       Connect  to  a  server at the given address.  Return a pair of buffered
1876       channels connected to the server.  Remember to call Pervasives.flush on
1877       the  output  channel  at the right times to ensure correct synchroniza‐
1878       tion.
1879
1880
1881
1882       val shutdown_connection : Pervasives.in_channel -> unit
1883
1884       ``Shut down'' a connection established with  UnixLabels.open_connection
1885       ;  that  is, transmit an end-of-file condition to the server reading on
1886       the other side of the connection.
1887
1888
1889
1890       val establish_server : (Pervasives.in_channel -> Pervasives.out_channel
1891       -> unit) -> addr:sockaddr -> unit
1892
1893       Establish  a  server on the given address.  The function given as first
1894       argument is called for each connection with two buffered channels  con‐
1895       nected to the client. A new process is created for each connection. The
1896       function UnixLabels.establish_server never returns normally.
1897
1898
1899
1900
1901       === Host and protocol databases ===
1902
1903
1904       type host_entry = Unix.host_entry = {
1905        h_name : string ;
1906        h_aliases : string array ;
1907        h_addrtype : socket_domain ;
1908        h_addr_list : inet_addr array ;
1909        }
1910
1911
1912       Structure of entries in the hosts database.
1913
1914
1915       type protocol_entry = Unix.protocol_entry = {
1916        p_name : string ;
1917        p_aliases : string array ;
1918        p_proto : int ;
1919        }
1920
1921
1922       Structure of entries in the protocols database.
1923
1924
1925       type service_entry = Unix.service_entry = {
1926        s_name : string ;
1927        s_aliases : string array ;
1928        s_port : int ;
1929        s_proto : string ;
1930        }
1931
1932
1933       Structure of entries in the services database.
1934
1935
1936
1937       val gethostname : unit -> string
1938
1939       Return the name of the local host.
1940
1941
1942
1943       val gethostbyname : string -> host_entry
1944
1945       Find an entry in hosts with the given name, or raise Not_found .
1946
1947
1948
1949       val gethostbyaddr : inet_addr -> host_entry
1950
1951       Find an entry in hosts with the given address, or raise Not_found .
1952
1953
1954
1955       val getprotobyname : string -> protocol_entry
1956
1957       Find an entry in protocols with the given name, or raise Not_found .
1958
1959
1960
1961       val getprotobynumber : int -> protocol_entry
1962
1963       Find an entry in protocols with the given  protocol  number,  or  raise
1964       Not_found .
1965
1966
1967
1968       val getservbyname : string -> protocol:string -> service_entry
1969
1970       Find an entry in services with the given name, or raise Not_found .
1971
1972
1973
1974       val getservbyport : int -> protocol:string -> service_entry
1975
1976       Find  an  entry  in  services  with  the given service number, or raise
1977       Not_found .
1978
1979
1980       type addr_info = {
1981        ai_family : socket_domain ;  (* Socket domain
1982        *)
1983        ai_socktype : socket_type ;  (* Socket type
1984        *)
1985        ai_protocol : int ;  (* Socket protocol number
1986        *)
1987        ai_addr : sockaddr ;  (* Address
1988        *)
1989        ai_canonname : string ;  (* Canonical host name
1990        *)
1991        }
1992
1993
1994       Address information returned by Unix.getaddrinfo .
1995
1996
1997       type getaddrinfo_option =
1998        | AI_FAMILY of socket_domain
1999         (* Impose the given socket domain
2000        *)
2001        | AI_SOCKTYPE of socket_type
2002         (* Impose the given socket type
2003        *)
2004        | AI_PROTOCOL of int
2005         (* Impose the given protocol
2006        *)
2007        | AI_NUMERICHOST  (* Do not call  name  resolver,  expect  numeric  IP
2008       address
2009        *)
2010        | AI_CANONNAME  (* Fill the ai_canonname field of the result
2011        *)
2012        | AI_PASSIVE  (* Set address to ``any'' address for use with Unix.bind
2013
2014        *)
2015
2016
2017       Options to Unix.getaddrinfo .
2018
2019
2020
2021       val  getaddrinfo  :  string  ->  string  ->  getaddrinfo_option list ->
2022       addr_info list
2023
2024
2025       getaddrinfo host service opts returns a list of Unix.addr_info  records
2026       describing  socket  parameters and addresses suitable for communicating
2027       with the given host and service.  The empty list  is  returned  if  the
2028       host or service names are unknown, or the constraints expressed in opts
2029       cannot be satisfied.
2030
2031
2032       host is either a host name  or  the  string  representation  of  an  IP
2033       address.   host  can  be  given  as the empty string; in this case, the
2034       ``any'' address or the ``loopback'' address are used, depending whether
2035       opts  contains  AI_PASSIVE  .   service is either a service name or the
2036       string representation of a port number.  service can be  given  as  the
2037       empty string; in this case, the port field of the returned addresses is
2038       set to 0.  opts is a possibly empty list of  options  that  allows  the
2039       caller  to  force  a  particular  socket domain (e.g. IPv6 only or IPv4
2040       only) or a particular socket type (e.g. TCP only or UDP only).
2041
2042
2043       type name_info = {
2044        ni_hostname : string ;  (* Name or IP address of host
2045        *)
2046        ni_service : string ;  (* Name of service or port number
2047        *)
2048        }
2049
2050
2051       Host and service information returned by Unix.getnameinfo .
2052
2053
2054       type getnameinfo_option =
2055        | NI_NOFQDN  (* Do not qualify local host names
2056        *)
2057        | NI_NUMERICHOST  (* Always return host as IP address
2058        *)
2059        | NI_NAMEREQD  (* Fail if host name cannot be determined
2060        *)
2061        | NI_NUMERICSERV  (* Always return service as port number
2062        *)
2063        | NI_DGRAM  (* Consider  the  service  as  UDP-based  instead  of  the
2064       default TCP
2065        *)
2066
2067
2068       Options to Unix.getnameinfo .
2069
2070
2071
2072       val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2073
2074
2075       getnameinfo  addr  opts  returns  the host name and service name corre‐
2076       sponding to the socket address addr .  opts is a possibly empty list of
2077       options  that governs how these names are obtained.  Raise Not_found if
2078       an error occurs.
2079
2080
2081
2082
2083       === Terminal interface ===
2084
2085
2086       === The following  functions  implement  the  POSIX  standard  terminal
2087       interface.  They  provide control over asynchronous communication ports
2088       and pseudo-terminals. Refer to the termios  man  page  for  a  complete
2089       description. ===
2090
2091
2092       type terminal_io = Unix.terminal_io = {
2093
2094       mutable c_ignbrk : bool ;  (* Ignore the break condition.
2095        *)
2096
2097       mutable c_brkint : bool ;  (* Signal interrupt on break condition.
2098        *)
2099
2100       mutable c_ignpar : bool ;  (* Ignore characters with parity errors.
2101        *)
2102
2103       mutable c_parmrk : bool ;  (* Mark parity errors.
2104        *)
2105
2106       mutable c_inpck : bool ;  (* Enable parity check on input.
2107        *)
2108
2109       mutable c_istrip : bool ;  (* Strip 8th bit on input characters.
2110        *)
2111
2112       mutable c_inlcr : bool ;  (* Map NL to CR on input.
2113        *)
2114
2115       mutable c_igncr : bool ;  (* Ignore CR on input.
2116        *)
2117
2118       mutable c_icrnl : bool ;  (* Map CR to NL on input.
2119        *)
2120
2121       mutable c_ixon : bool ;  (* Recognize XON/XOFF characters on input.
2122        *)
2123
2124       mutable c_ixoff : bool ;  (* Emit XON/XOFF chars to control input flow.
2125        *)
2126
2127       mutable c_opost : bool ;  (* Enable output processing.
2128        *)
2129
2130       mutable  c_obaud  :  int  ;  (* Output baud rate (0 means close connec‐
2131       tion).
2132        *)
2133
2134       mutable c_ibaud : int ;  (* Input baud rate.
2135        *)
2136
2137       mutable c_csize : int ;  (* Number of bits per character (5-8).
2138        *)
2139
2140       mutable c_cstopb : int ;  (* Number of stop bits (1-2).
2141        *)
2142
2143       mutable c_cread : bool ;  (* Reception is enabled.
2144        *)
2145
2146       mutable c_parenb : bool ;  (* Enable parity generation and detection.
2147        *)
2148
2149       mutable c_parodd : bool ;  (* Specify odd parity instead of even.
2150        *)
2151
2152       mutable c_hupcl : bool ;  (* Hang up on last close.
2153        *)
2154
2155       mutable c_clocal : bool ;  (* Ignore modem status lines.
2156        *)
2157
2158       mutable c_isig : bool ;  (* Generate signal on INTR, QUIT, SUSP.
2159        *)
2160
2161       mutable c_icanon : bool ;  (* Enable canonical processing (line buffer‐
2162       ing and editing)
2163        *)
2164
2165       mutable c_noflsh : bool ;  (* Disable flush after INTR, QUIT, SUSP.
2166        *)
2167
2168       mutable c_echo : bool ;  (* Echo input characters.
2169        *)
2170
2171       mutable c_echoe : bool ;  (* Echo ERASE (to erase previous character).
2172        *)
2173
2174       mutable c_echok : bool ;  (* Echo KILL (to erase the current line).
2175        *)
2176
2177       mutable c_echonl : bool ;  (* Echo NL even if c_echo is not set.
2178        *)
2179
2180       mutable c_vintr : char ;  (* Interrupt character (usually ctrl-C).
2181        *)
2182
2183       mutable c_vquit : char ;  (* Quit character (usually ctrl-\).
2184        *)
2185
2186       mutable c_verase : char ;  (* Erase character (usually DEL or ctrl-H).
2187        *)
2188
2189       mutable c_vkill : char ;  (* Kill line character (usually ctrl-U).
2190        *)
2191
2192       mutable c_veof : char ;  (* End-of-file character (usually ctrl-D).
2193        *)
2194
2195       mutable c_veol : char ;  (* Alternate end-of-line char. (usually none).
2196        *)
2197
2198       mutable  c_vmin : int ;  (* Minimum number of characters to read before
2199       the read request is satisfied.
2200        *)
2201
2202       mutable c_vtime : int ;  (* Maximum read wait (in 0.1s units).
2203        *)
2204
2205       mutable c_vstart : char ;  (* Start character (usually ctrl-Q).
2206        *)
2207
2208       mutable c_vstop : char ;  (* Stop character (usually ctrl-S).
2209        *)
2210        }
2211
2212
2213
2214
2215
2216       val tcgetattr : file_descr -> terminal_io
2217
2218       Return the status of  the  terminal  referred  to  by  the  given  file
2219       descriptor.
2220
2221
2222       type setattr_when = Unix.setattr_when =
2223        | TCSANOW
2224        | TCSADRAIN
2225        | TCSAFLUSH
2226
2227
2228
2229
2230
2231       val tcsetattr : file_descr -> mode:setattr_when -> terminal_io -> unit
2232
2233       Set  the  status of the terminal referred to by the given file descrip‐
2234       tor. The second argument indicates when the status change takes  place:
2235       immediately ( TCSANOW ), when all pending output has been transmitted (
2236       TCSADRAIN ), or after flushing all input that has been received but not
2237       read  ( TCSAFLUSH ).  TCSADRAIN is recommended when changing the output
2238       parameters; TCSAFLUSH , when changing the input parameters.
2239
2240
2241
2242       val tcsendbreak : file_descr -> duration:int -> unit
2243
2244       Send a break condition on the given file descriptor.  The second  argu‐
2245       ment  is  the  duration  of  the break, in 0.1s units; 0 means standard
2246       duration (0.25s).
2247
2248
2249
2250       val tcdrain : file_descr -> unit
2251
2252       Waits until all output written on the given file  descriptor  has  been
2253       transmitted.
2254
2255
2256       type flush_queue = Unix.flush_queue =
2257        | TCIFLUSH
2258        | TCOFLUSH
2259        | TCIOFLUSH
2260
2261
2262
2263
2264
2265       val tcflush : file_descr -> mode:flush_queue -> unit
2266
2267       Discard data written on the given file descriptor but not yet transmit‐
2268       ted, or data received but not yet read, depending on the  second  argu‐
2269       ment:  TCIFLUSH  flushes  data  received but not read, TCOFLUSH flushes
2270       data written but not transmitted, and TCIOFLUSH flushes both.
2271
2272
2273       type flow_action = Unix.flow_action =
2274        | TCOOFF
2275        | TCOON
2276        | TCIOFF
2277        | TCION
2278
2279
2280
2281
2282
2283       val tcflow : file_descr -> mode:flow_action -> unit
2284
2285       Suspend or restart reception or transmission of data on the given  file
2286       descriptor,  depending  on the second argument: TCOOFF suspends output,
2287       TCOON restarts output, TCIOFF transmits a  STOP  character  to  suspend
2288       input, and TCION transmits a START character to restart input.
2289
2290
2291
2292       val setsid : unit -> int
2293
2294       Put  the  calling  process in a new session and detach it from its con‐
2295       trolling terminal.
2296
2297
2298
2299
2300
2301OCamldoc                          2019-02-02                     UnixLabels(3)
Impressum