1UnixLabels(3) OCaml library UnixLabels(3)
2
6 UnixLabels - Interface to the Unix system.
7
9 Module UnixLabels
10
12 Module UnixLabels
13 : sig end
14 Interface to the Unix system.
17 To use the labeled version of this module, add module Unix = UnixLabels
19 in your implementation.
20 Note: all the functions of this module (except UnixLabels.error_message
22 and UnixLabels.handle_unix_error ) are liable to raise the UnixLa‐
23 bels.Unix_error exception whenever the underlying system call signals
24 an error.
25 Error report
33 type error = Unix.error =
34 | E2BIG (* Argument list too long
35 *)
36 | EACCES (* Permission denied
37 *)
38 | EAGAIN (* Resource temporarily unavailable; try again
39 *)
40 | EBADF (* Bad file descriptor
41 *)
42 | EBUSY (* Resource unavailable
43 *)
44 | ECHILD (* No child process
45 *)
46 | EDEADLK (* Resource deadlock would occur
47 *)
48 | EDOM (* Domain error for math functions, etc.
49 *)
50 | EEXIST (* File exists
51 *)
52 | EFAULT (* Bad address
53 *)
54 | EFBIG (* File too large
55 *)
56 | EINTR (* Function interrupted by signal
57 *)
58 | EINVAL (* Invalid argument
59 *)
60 | EIO (* Hardware I/O error
61 *)
62 | EISDIR (* Is a directory
63 *)
64 | EMFILE (* Too many open files by the process
65 *)
66 | EMLINK (* Too many links
67 *)
68 | ENAMETOOLONG (* Filename too long
69 *)
70 | ENFILE (* Too many open files in the system
71 *)
72 | ENODEV (* No such device
73 *)
74 | ENOENT (* No such file or directory
75 *)
76 | ENOEXEC (* Not an executable file
77 *)
78 | ENOLCK (* No locks available
79 *)
80 | ENOMEM (* Not enough memory
81 *)
82 | ENOSPC (* No space left on device
83 *)
84 | ENOSYS (* Function not supported
85 *)
86 | ENOTDIR (* Not a directory
87 *)
88 | ENOTEMPTY (* Directory not empty
89 *)
90 | ENOTTY (* Inappropriate I/O control operation
91 *)
92 | ENXIO (* No such device or address
93 *)
94 | EPERM (* Operation not permitted
95 *)
96 | EPIPE (* Broken pipe
97 *)
98 | ERANGE (* Result too large
99 *)
100 | EROFS (* Read-only file system
101 *)
102 | ESPIPE (* Invalid seek e.g. on a pipe
103 *)
104 | ESRCH (* No such process
105 *)
106 | EXDEV (* Invalid link
107 *)
108 | EWOULDBLOCK (* Operation would block
109 *)
110 | EINPROGRESS (* Operation now in progress
111 *)
112 | EALREADY (* Operation already in progress
113 *)
114 | ENOTSOCK (* Socket operation on non-socket
115 *)
116 | EDESTADDRREQ (* Destination address required
117 *)
118 | EMSGSIZE (* Message too long
119 *)
120 | EPROTOTYPE (* Protocol wrong type for socket
121 *)
122 | ENOPROTOOPT (* Protocol not available
123 *)
124 | EPROTONOSUPPORT (* Protocol not supported
125 *)
126 | ESOCKTNOSUPPORT (* Socket type not supported
127 *)
128 | EOPNOTSUPP (* Operation not supported on socket
129 *)
130 | EPFNOSUPPORT (* Protocol family not supported
131 *)
132 | EAFNOSUPPORT (* Address family not supported by protocol family
133 *)
134 | EADDRINUSE (* Address already in use
135 *)
136 | EADDRNOTAVAIL (* Can't assign requested address
137 *)
138 | ENETDOWN (* Network is down
139 *)
140 | ENETUNREACH (* Network is unreachable
141 *)
142 | ENETRESET (* Network dropped connection on reset
143 *)
144 | ECONNABORTED (* Software caused connection abort
145 *)
146 | ECONNRESET (* Connection reset by peer
147 *)
148 | ENOBUFS (* No buffer space available
149 *)
150 | EISCONN (* Socket is already connected
151 *)
152 | ENOTCONN (* Socket is not connected
153 *)
154 | ESHUTDOWN (* Can't send after socket shutdown
155 *)
156 | ETOOMANYREFS (* Too many references: can't splice
157 *)
158 | ETIMEDOUT (* Connection timed out
159 *)
160 | ECONNREFUSED (* Connection refused
161 *)
162 | EHOSTDOWN (* Host is down
163 *)
164 | EHOSTUNREACH (* No route to host
165 *)
166 | ELOOP (* Too many levels of symbolic links
167 *)
168 | EOVERFLOW (* File size or position not representable
169 *)
170 | EUNKNOWNERR of int
171 (* Unknown error
172 *)
173 The type of error codes. Errors defined in the POSIX standard and ad‐
176 ditional errors from UNIX98 and BSD. All other errors are mapped to
177 EUNKNOWNERR.
178 exception Unix_error of error * string * string
182 Raised by the system calls below when an error is encountered. The
185 first component is the error code; the second component is the function
186 name; the third component is the string parameter to the function, if
187 it has one, or the empty string otherwise.
188 UnixLabels.Unix_error and Unix.Unix_error are the same, and catching
191 one will catch the other.
192 val error_message : error -> string
196 Return a string describing the given error code.
198 val handle_unix_error : ('a -> 'b) -> 'a -> 'b
202 handle_unix_error f x applies f to x and returns the result. If the
205 exception UnixLabels.Unix_error is raised, it prints a message describ‐
206 ing the error and exits with code 2.
207 Access to the process environment
212 val environment : unit -> string array
213 Return the process environment, as an array of strings with the format
215 ``variable=value''. The returned array is empty if the process has
216 special privileges.
217 val unsafe_environment : unit -> string array
221 Return the process environment, as an array of strings with the format
223 ``variable=value''. Unlike UnixLabels.environment , this function re‐
224 turns a populated array even if the process has special privileges.
225 See the documentation for UnixLabels.unsafe_getenv for more details.
226 Since 4.12.0
229 val getenv : string -> string
233 Return the value associated to a variable in the process environment,
235 unless the process has special privileges.
236 Raises Not_found if the variable is unbound or the process has special
239 privileges.
240 This function is identical to Sys.getenv .
242 val unsafe_getenv : string -> string
246 Return the value associated to a variable in the process environment.
248 Unlike UnixLabels.getenv , this function returns the value even if the
250 process has special privileges. It is considered unsafe because the
251 programmer of a setuid or setgid program must be careful to avoid using
252 maliciously crafted environment variables in the search path for exe‐
253 cutables, the locations for temporary files or logs, and the like.
254 Since 4.06.0
257 Raises Not_found if the variable is unbound.
260 val putenv : string -> string -> unit
264 putenv name value sets the value associated to a variable in the
267 process environment. name is the name of the environment variable, and
268 value its new associated value.
269 Process handling
274 type process_status = Unix.process_status =
275 | WEXITED of int
276 (* The process terminated normally by exit ; the argument is the re‐
277 turn code.
278 *)
279 | WSIGNALED of int
280 (* The process was killed by a signal; the argument is the signal
281 number.
282 *)
283 | WSTOPPED of int
284 (* The process was stopped by a signal; the argument is the signal
285 number.
286 *)
287 The termination status of a process. See module Sys for the defini‐
290 tions of the standard signal numbers. Note that they are not the num‐
291 bers used by the OS.
292 type wait_flag = Unix.wait_flag =
295 | WNOHANG (* Do not block if no child has died yet, but immediately
296 return with a pid equal to 0.
297 *)
298 | WUNTRACED (* Report also the children that receive stop signals.
299 *)
300 Flags for UnixLabels.waitpid .
303 val execv : prog:string -> args:string array -> 'a
307 execv ~prog ~args execute the program in file prog , with the arguments
310 args , and the current process environment. These execv* functions
311 never return: on success, the current program is replaced by the new
312 one.
313 Raises Unix_error on failure
316 val execve : prog:string -> args:string array -> env:string array -> 'a
320 Same as UnixLabels.execv , except that the third argument provides the
322 environment to the program executed.
323 val execvp : prog:string -> args:string array -> 'a
327 Same as UnixLabels.execv , except that the program is searched in the
329 path.
330 val execvpe : prog:string -> args:string array -> env:string array ->
334 'a
335 Same as UnixLabels.execve , except that the program is searched in the
337 path.
338 val fork : unit -> int
342 Fork a new process. The returned integer is 0 for the child process,
344 the pid of the child process for the parent process.
345 Raises Invalid_argument on Windows. Use UnixLabels.create_process or
348 threads instead.
349 val wait : unit -> int * process_status
353 Wait until one of the children processes die, and return its pid and
355 termination status.
356 Raises Invalid_argument on Windows. Use UnixLabels.waitpid instead.
359 val waitpid : mode:wait_flag list -> int -> int * process_status
363 Same as UnixLabels.wait , but waits for the child process whose pid is
365 given. A pid of -1 means wait for any child. A pid of 0 means wait
366 for any child in the same process group as the current process. Nega‐
367 tive pid arguments represent process groups. The list of options indi‐
368 cates whether waitpid should return immediately without waiting, and
369 whether it should report stopped children.
370 On Windows: can only wait for a given PID, not any child process.
372 val system : string -> process_status
376 Execute the given command, wait until it terminates, and return its
378 termination status. The string is interpreted by the shell /bin/sh (or
379 the command interpreter cmd.exe on Windows) and therefore can contain
380 redirections, quotes, variables, etc. To properly quote whitespace and
381 shell special characters occurring in file names or command arguments,
382 the use of Filename.quote_command is recommended. The result WEXITED
383 127 indicates that the shell couldn't be executed.
384 val _exit : int -> 'a
388 Terminate the calling process immediately, returning the given status
390 code to the operating system: usually 0 to indicate no errors, and a
391 small positive integer to indicate failure. Unlike exit , Unix._exit
392 performs no finalization whatsoever: functions registered with at_exit
393 are not called, input/output channels are not flushed, and the C
394 run-time system is not finalized either.
395 The typical use of Unix._exit is after a Unix.fork operation, when the
397 child process runs into a fatal error and must exit. In this case, it
398 is preferable to not perform any finalization action in the child
399 process, as these actions could interfere with similar actions per‐
400 formed by the parent process. For example, output channels should not
401 be flushed by the child process, as the parent process may flush them
402 again later, resulting in duplicate output.
403 Since 4.12.0
406 val getpid : unit -> int
410 Return the pid of the process.
412 val getppid : unit -> int
416 Return the pid of the parent process.
418 Raises Invalid_argument on Windows (because it is meaningless)
421 val nice : int -> int
425 Change the process priority. The integer argument is added to the
427 ``nice'' value. (Higher values of the ``nice'' value mean lower priori‐
428 ties.) Return the new nice value.
429 Raises Invalid_argument on Windows
432 Basic file input/output
437 type file_descr = Unix.file_descr
438 The abstract type of file descriptors.
441 val stdin : file_descr
445 File descriptor for standard input.
447 val stdout : file_descr
451 File descriptor for standard output.
453 val stderr : file_descr
457 File descriptor for standard error.
459 type open_flag = Unix.open_flag =
462 | O_RDONLY (* Open for reading
463 *)
464 | O_WRONLY (* Open for writing
465 *)
466 | O_RDWR (* Open for reading and writing
467 *)
468 | O_NONBLOCK (* Open in non-blocking mode
469 *)
470 | O_APPEND (* Open for append
471 *)
472 | O_CREAT (* Create if nonexistent
473 *)
474 | O_TRUNC (* Truncate to 0 length if existing
475 *)
476 | O_EXCL (* Fail if existing
477 *)
478 | O_NOCTTY (* Don't make this dev a controlling tty
479 *)
480 | O_DSYNC (* Writes complete as `Synchronised I/O data integrity com‐
481 pletion'
482 *)
483 | O_SYNC (* Writes complete as `Synchronised I/O file integrity com‐
484 pletion'
485 *)
486 | O_RSYNC (* Reads complete as writes (depending on O_SYNC/O_DSYNC)
487 *)
488 | O_SHARE_DELETE (* Windows only: allow the file to be deleted while
489 still open
490 *)
491 | O_CLOEXEC (* Set the close-on-exec flag on the descriptor returned
492 by UnixLabels.openfile . See UnixLabels.set_close_on_exec for more in‐
493 formation.
494 *)
495 | O_KEEPEXEC (* Clear the close-on-exec flag. This is currently the
496 default.
497 *)
498 The flags to UnixLabels.openfile .
501 type file_perm = int
504 The type of file access rights, e.g. 0o640 is read and write for user,
507 read for group, none for others
508 val openfile : string -> mode:open_flag list -> perm:file_perm ->
512 file_descr
513 Open the named file with the given flags. Third argument is the permis‐
515 sions to give to the file if it is created (see UnixLabels.umask ). Re‐
516 turn a file descriptor on the named file.
517 val close : file_descr -> unit
521 Close a file descriptor.
523 val fsync : file_descr -> unit
527 Flush file buffers to disk.
529 Since 4.12.0
532 val read : file_descr -> buf:bytes -> pos:int -> len:int -> int
536 read fd ~buf ~pos ~len reads len bytes from descriptor fd , storing
539 them in byte sequence buf , starting at position pos in buf . Return
540 the number of bytes actually read.
541 val write : file_descr -> buf:bytes -> pos:int -> len:int -> int
545 write fd ~buf ~pos ~len writes len bytes to descriptor fd , taking them
548 from byte sequence buf , starting at position pos in buff . Return the
549 number of bytes actually written. write repeats the writing operation
550 until all bytes have been written or an error occurs.
551 val single_write : file_descr -> buf:bytes -> pos:int -> len:int -> int
555 Same as UnixLabels.write , but attempts to write only once. Thus, if
557 an error occurs, single_write guarantees that no data has been written.
558 val write_substring : file_descr -> buf:string -> pos:int -> len:int ->
562 int
563 Same as UnixLabels.write , but take the data from a string instead of a
565 byte sequence.
566 Since 4.02.0
569 val single_write_substring : file_descr -> buf:string -> pos:int ->
573 len:int -> int
574 Same as UnixLabels.single_write , but take the data from a string in‐
576 stead of a byte sequence.
577 Since 4.02.0
580 Interfacing with the standard input/output library
585 val in_channel_of_descr : file_descr -> in_channel
586 Create an input channel reading from the given descriptor. The channel
588 is initially in binary mode; use set_binary_mode_in ic false if text
589 mode is desired. Text mode is supported only if the descriptor refers
590 to a file or pipe, but is not supported if it refers to a socket.
591 On Windows: set_binary_mode_in always fails on channels created with
593 this function.
594 Beware that input channels are buffered, so more characters may have
596 been read from the descriptor than those accessed using channel func‐
597 tions. Channels also keep a copy of the current position in the file.
598 Closing the channel ic returned by in_channel_of_descr fd using
600 close_in ic also closes the underlying descriptor fd . It is incorrect
601 to close both the channel ic and the descriptor fd .
602 If several channels are created on the same descriptor, one of the
604 channels must be closed, but not the others. Consider for example a
605 descriptor s connected to a socket and two channels ic = in_chan‐
606 nel_of_descr s and oc = out_channel_of_descr s . The recommended clos‐
607 ing protocol is to perform close_out oc , which flushes buffered output
608 to the socket then closes the socket. The ic channel must not be
609 closed and will be collected by the GC eventually.
610 val out_channel_of_descr : file_descr -> out_channel
614 Create an output channel writing on the given descriptor. The channel
616 is initially in binary mode; use set_binary_mode_out oc false if text
617 mode is desired. Text mode is supported only if the descriptor refers
618 to a file or pipe, but is not supported if it refers to a socket.
619 On Windows: set_binary_mode_out always fails on channels created with
621 this function.
622 Beware that output channels are buffered, so you may have to call flush
624 to ensure that all data has been sent to the descriptor. Channels also
625 keep a copy of the current position in the file.
626 Closing the channel oc returned by out_channel_of_descr fd using
628 close_out oc also closes the underlying descriptor fd . It is incor‐
629 rect to close both the channel ic and the descriptor fd .
630 See Unix.in_channel_of_descr for a discussion of the closing protocol
632 when several channels are created on the same descriptor.
633 val descr_of_in_channel : in_channel -> file_descr
637 Return the descriptor corresponding to an input channel.
639 val descr_of_out_channel : out_channel -> file_descr
643 Return the descriptor corresponding to an output channel.
645 Seeking and truncating
650 type seek_command = Unix.seek_command =
651 | SEEK_SET (* indicates positions relative to the beginning of the
652 file
653 *)
654 | SEEK_CUR (* indicates positions relative to the current position
655 *)
656 | SEEK_END (* indicates positions relative to the end of the file
657 *)
658 Positioning modes for UnixLabels.lseek .
661 val lseek : file_descr -> int -> mode:seek_command -> int
665 Set the current position for a file descriptor, and return the result‐
667 ing offset (from the beginning of the file).
668 val truncate : string -> len:int -> unit
672 Truncates the named file to the given size.
674 val ftruncate : file_descr -> len:int -> unit
678 Truncates the file corresponding to the given descriptor to the given
680 size.
681 File status
686 type file_kind = Unix.file_kind =
687 | S_REG (* Regular file
688 *)
689 | S_DIR (* Directory
690 *)
691 | S_CHR (* Character device
692 *)
693 | S_BLK (* Block device
694 *)
695 | S_LNK (* Symbolic link
696 *)
697 | S_FIFO (* Named pipe
698 *)
699 | S_SOCK (* Socket
700 *)
701 type stats = Unix.stats = {
706 st_dev : int ; (* Device number
707 *)
708 st_ino : int ; (* Inode number
709 *)
710 st_kind : file_kind ; (* Kind of the file
711 *)
712 st_perm : file_perm ; (* Access rights
713 *)
714 st_nlink : int ; (* Number of links
715 *)
716 st_uid : int ; (* User id of the owner
717 *)
718 st_gid : int ; (* Group ID of the file's group
719 *)
720 st_rdev : int ; (* Device ID (if special file)
721 *)
722 st_size : int ; (* Size in bytes
723 *)
724 st_atime : float ; (* Last access time
725 *)
726 st_mtime : float ; (* Last modification time
727 *)
728 st_ctime : float ; (* Last status change time
729 *)
730 }
731 The information returned by the UnixLabels.stat calls.
734 val stat : string -> stats
738 Return the information for the named file.
740 val lstat : string -> stats
744 Same as UnixLabels.stat , but in case the file is a symbolic link, re‐
746 turn the information for the link itself.
747 val fstat : file_descr -> stats
751 Return the information for the file associated with the given descrip‐
753 tor.
754 val isatty : file_descr -> bool
758 Return true if the given file descriptor refers to a terminal or con‐
760 sole window, false otherwise.
761 File operations on large files
766 module LargeFile : sig end
767 File operations on large files. This sub-module provides 64-bit vari‐
770 ants of the functions UnixLabels.LargeFile.lseek (for positioning a
771 file descriptor), UnixLabels.LargeFile.truncate and UnixLabels.Large‐
772 File.ftruncate (for changing the size of a file), and UnixLabels.Large‐
773 File.stat , UnixLabels.LargeFile.lstat and UnixLabels.LargeFile.fstat
774 (for obtaining information on files). These alternate functions repre‐
775 sent positions and sizes by 64-bit integers (type int64 ) instead of
776 regular integers (type int ), thus allowing operating on files whose
777 sizes are greater than max_int .
778 Mapping files into memory
783 val map_file : file_descr -> ?pos:int64 -> kind:('a, 'b) Bigarray.kind
784 -> layout:'c Bigarray.layout -> shared:bool -> dims:int array -> ('a,
785 'b, 'c) Bigarray.Genarray.t
786 Memory mapping of a file as a Bigarray. map_file fd ~kind ~layout
788 ~shared ~dims returns a Bigarray of kind kind , layout layout , and di‐
789 mensions as specified in dims . The data contained in this Bigarray
790 are the contents of the file referred to by the file descriptor fd (as
791 opened previously with UnixLabels.openfile , for example). The op‐
792 tional pos parameter is the byte offset in the file of the data being
793 mapped; it defaults to 0 (map from the beginning of the file).
794 If shared is true , all modifications performed on the array are re‐
796 flected in the file. This requires that fd be opened with write per‐
797 missions. If shared is false , modifications performed on the array
798 are done in memory only, using copy-on-write of the modified pages; the
799 underlying file is not affected.
800 Genarray.map_file is much more efficient than reading the whole file in
803 a Bigarray, modifying that Bigarray, and writing it afterwards.
804 To adjust automatically the dimensions of the Bigarray to the actual
806 size of the file, the major dimension (that is, the first dimension for
807 an array with C layout, and the last dimension for an array with For‐
808 tran layout) can be given as -1 . Genarray.map_file then determines
809 the major dimension from the size of the file. The file must contain
810 an integral number of sub-arrays as determined by the non-major dimen‐
811 sions, otherwise Failure is raised.
812 If all dimensions of the Bigarray are given, the file size is matched
814 against the size of the Bigarray. If the file is larger than the Bi‐
815 garray, only the initial portion of the file is mapped to the Bigarray.
816 If the file is smaller than the big array, the file is automatically
817 grown to the size of the Bigarray. This requires write permissions on
818 fd .
819 Array accesses are bounds-checked, but the bounds are determined by the
821 initial call to map_file . Therefore, you should make sure no other
822 process modifies the mapped file while you're accessing it, or a SIGBUS
823 signal may be raised. This happens, for instance, if the file is
824 shrunk.
825 Invalid_argument or Failure may be raised in cases where argument vali‐
828 dation fails.
829 Since 4.06.0
832 Operations on file names
837 val unlink : string -> unit
838 Removes the named file.
840 If the named file is a directory, raises:
842 - EPERM on POSIX compliant system
844 - EISDIR on Linux >= 2.1.132
846 - EACCESS on Windows
848 val rename : src:string -> dst:string -> unit
853 rename ~src ~dst changes the name of a file from src to dst , moving it
856 between directories if needed. If dst already exists, its contents
857 will be replaced with those of src . Depending on the operating sys‐
858 tem, the metadata (permissions, owner, etc) of dst can either be pre‐
859 served or be replaced by those of src .
860 val link : ?follow:bool -> src:string -> dst:string -> unit
864 link ?follow ~src ~dst creates a hard link named dst to the file named
867 src .
868 Raises ENOSYS On Unix if ~follow:_ is requested, but linkat is unavail‐
871 able.
872 Raises ENOSYS On Windows if ~follow:false is requested.
875 val realpath : string -> string
879 realpath p is an absolute pathname for p obtained by resolving all ex‐
882 tra / characters, relative path segments and symbolic links.
883 Since 4.13.0
886 File permissions and ownership
891 type access_permission = Unix.access_permission =
892 | R_OK (* Read permission
893 *)
894 | W_OK (* Write permission
895 *)
896 | X_OK (* Execution permission
897 *)
898 | F_OK (* File exists
899 *)
900 Flags for the UnixLabels.access call.
903 val chmod : string -> perm:file_perm -> unit
907 Change the permissions of the named file.
909 val fchmod : file_descr -> perm:file_perm -> unit
913 Change the permissions of an opened file.
915 Raises Invalid_argument on Windows
918 val chown : string -> uid:int -> gid:int -> unit
922 Change the owner uid and owner gid of the named file.
924 Raises Invalid_argument on Windows
927 val fchown : file_descr -> uid:int -> gid:int -> unit
931 Change the owner uid and owner gid of an opened file.
933 Raises Invalid_argument on Windows
936 val umask : int -> int
940 Set the process's file mode creation mask, and return the previous
942 mask.
943 Raises Invalid_argument on Windows
946 val access : string -> perm:access_permission list -> unit
950 Check that the process has the given permissions over the named file.
952 On Windows: execute permission X_OK cannot be tested, just tests for
954 read permission instead.
955 Raises Unix_error otherwise.
958 Operations on file descriptors
963 val dup : ?cloexec:bool -> file_descr -> file_descr
964 Return a new file descriptor referencing the same file as the given de‐
966 scriptor. See UnixLabels.set_close_on_exec for documentation on the
967 cloexec optional argument.
968 val dup2 : ?cloexec:bool -> src:file_descr -> dst:file_descr -> unit
972 dup2 ~src ~dst duplicates src to dst , closing dst if already opened.
975 See UnixLabels.set_close_on_exec for documentation on the cloexec op‐
976 tional argument.
977 val set_nonblock : file_descr -> unit
981 Set the ``non-blocking'' flag on the given descriptor. When the
983 non-blocking flag is set, reading on a descriptor on which there is
984 temporarily no data available raises the EAGAIN or EWOULDBLOCK error
985 instead of blocking; writing on a descriptor on which there is tempo‐
986 rarily no room for writing also raises EAGAIN or EWOULDBLOCK .
987 val clear_nonblock : file_descr -> unit
991 Clear the ``non-blocking'' flag on the given descriptor. See UnixLa‐
993 bels.set_nonblock .
994 val set_close_on_exec : file_descr -> unit
998 Set the ``close-on-exec'' flag on the given descriptor. A descriptor
1000 with the close-on-exec flag is automatically closed when the current
1001 process starts another program with one of the exec , create_process
1002 and open_process functions.
1003 It is often a security hole to leak file descriptors opened on, say, a
1005 private file to an external program: the program, then, gets access to
1006 the private file and can do bad things with it. Hence, it is highly
1007 recommended to set all file descriptors ``close-on-exec'', except in
1008 the very few cases where a file descriptor actually needs to be trans‐
1009 mitted to another program.
1010 The best way to set a file descriptor ``close-on-exec'' is to create it
1012 in this state. To this end, the openfile function has O_CLOEXEC and
1013 O_KEEPEXEC flags to enforce ``close-on-exec'' mode or ``keep-on-exec''
1014 mode, respectively. All other operations in the Unix module that cre‐
1015 ate file descriptors have an optional argument ?cloexec:bool to indi‐
1016 cate whether the file descriptor should be created in ``close-on-exec''
1017 mode (by writing ~cloexec:true ) or in ``keep-on-exec'' mode (by writ‐
1018 ing ~cloexec:false ). For historical reasons, the default file de‐
1019 scriptor creation mode is ``keep-on-exec'', if no cloexec optional ar‐
1020 gument is given. This is not a safe default, hence it is highly recom‐
1021 mended to pass explicit cloexec arguments to operations that create
1022 file descriptors.
1023 The cloexec optional arguments and the O_KEEPEXEC flag were introduced
1025 in OCaml 4.05. Earlier, the common practice was to create file de‐
1026 scriptors in the default, ``keep-on-exec'' mode, then call
1027 set_close_on_exec on those freshly-created file descriptors. This is
1028 not as safe as creating the file descriptor in ``close-on-exec'' mode
1029 because, in multithreaded programs, a window of vulnerability exists
1030 between the time when the file descriptor is created and the time
1031 set_close_on_exec completes. If another thread spawns another program
1032 during this window, the descriptor will leak, as it is still in the
1033 ``keep-on-exec'' mode.
1034 Regarding the atomicity guarantees given by ~cloexec:true or by the use
1036 of the O_CLOEXEC flag: on all platforms it is guaranteed that a concur‐
1037 rently-executing Caml thread cannot leak the descriptor by starting a
1038 new process. On Linux, this guarantee extends to concurrently-execut‐
1039 ing C threads. As of Feb 2017, other operating systems lack the neces‐
1040 sary system calls and still expose a window of vulnerability during
1041 which a C thread can see the newly-created file descriptor in
1042 ``keep-on-exec'' mode.
1043 val clear_close_on_exec : file_descr -> unit
1047 Clear the ``close-on-exec'' flag on the given descriptor. See UnixLa‐
1049 bels.set_close_on_exec .
1050 Directories
1055 val mkdir : string -> perm:file_perm -> unit
1056 Create a directory with the given permissions (see UnixLabels.umask ).
1058 val rmdir : string -> unit
1062 Remove an empty directory.
1064 val chdir : string -> unit
1068 Change the process working directory.
1070 val getcwd : unit -> string
1074 Return the name of the current working directory.
1076 val chroot : string -> unit
1080 Change the process root directory.
1082 Raises Invalid_argument on Windows
1085 type dir_handle = Unix.dir_handle
1088 The type of descriptors over opened directories.
1091 val opendir : string -> dir_handle
1095 Open a descriptor on a directory
1097 val readdir : dir_handle -> string
1101 Return the next entry in a directory.
1103 Raises End_of_file when the end of the directory has been reached.
1106 val rewinddir : dir_handle -> unit
1110 Reposition the descriptor to the beginning of the directory
1112 val closedir : dir_handle -> unit
1116 Close a directory descriptor.
1118 Pipes and redirections
1123 val pipe : ?cloexec:bool -> unit -> file_descr * file_descr
1124 Create a pipe. The first component of the result is opened for reading,
1126 that's the exit to the pipe. The second component is opened for writ‐
1127 ing, that's the entrance to the pipe. See UnixLabels.set_close_on_exec
1128 for documentation on the cloexec optional argument.
1129 val mkfifo : string -> perm:file_perm -> unit
1133 Create a named pipe with the given permissions (see UnixLabels.umask ).
1135 Raises Invalid_argument on Windows
1138 High-level process and redirection management
1143 val create_process : prog:string -> args:string array -> stdin:file_de‐
1144 scr -> stdout:file_descr -> stderr:file_descr -> int
1145 create_process ~prog ~args ~stdin ~stdout ~stderr forks a new process
1148 that executes the program in file prog , with arguments args . The pid
1149 of the new process is returned immediately; the new process executes
1150 concurrently with the current process. The standard input and outputs
1151 of the new process are connected to the descriptors stdin , stdout and
1152 stderr . Passing e.g. Unix.stdout for stdout prevents the redirection
1153 and causes the new process to have the same standard output as the cur‐
1154 rent process. The executable file prog is searched in the path. The
1155 new process has the same environment as the current process.
1156 val create_process_env : prog:string -> args:string array -> env:string
1160 array -> stdin:file_descr -> stdout:file_descr -> stderr:file_descr ->
1161 int
1162 create_process_env ~prog ~args ~env ~stdin ~stdout ~stderr works as
1165 UnixLabels.create_process , except that the extra argument env speci‐
1166 fies the environment passed to the program.
1167 val open_process_in : string -> in_channel
1171 High-level pipe and process management. This function runs the given
1173 command in parallel with the program. The standard output of the com‐
1174 mand is redirected to a pipe, which can be read via the returned input
1175 channel. The command is interpreted by the shell /bin/sh (or cmd.exe
1176 on Windows), cf. UnixLabels.system . The Filename.quote_command func‐
1177 tion can be used to quote the command and its arguments as appropriate
1178 for the shell being used. If the command does not need to be run
1179 through the shell, UnixLabels.open_process_args_in can be used as a
1180 more robust and more efficient alternative to UnixLa‐
1181 bels.open_process_in .
1182 val open_process_out : string -> out_channel
1186 Same as UnixLabels.open_process_in , but redirect the standard input of
1188 the command to a pipe. Data written to the returned output channel is
1189 sent to the standard input of the command. Warning: writes on output
1190 channels are buffered, hence be careful to call flush at the right
1191 times to ensure correct synchronization. If the command does not need
1192 to be run through the shell, UnixLabels.open_process_args_out can be
1193 used instead of UnixLabels.open_process_out .
1194 val open_process : string -> in_channel * out_channel
1198 Same as UnixLabels.open_process_out , but redirects both the standard
1200 input and standard output of the command to pipes connected to the two
1201 returned channels. The input channel is connected to the output of the
1202 command, and the output channel to the input of the command. If the
1203 command does not need to be run through the shell, UnixLa‐
1204 bels.open_process_args can be used instead of UnixLabels.open_process .
1205 val open_process_full : string -> env:string array -> in_channel *
1209 out_channel * in_channel
1210 Similar to UnixLabels.open_process , but the second argument specifies
1212 the environment passed to the command. The result is a triple of chan‐
1213 nels connected respectively to the standard output, standard input, and
1214 standard error of the command. If the command does not need to be run
1215 through the shell, UnixLabels.open_process_args_full can be used in‐
1216 stead of UnixLabels.open_process_full .
1217 val open_process_args_in : string -> string array -> in_channel
1221 open_process_args_in prog args runs the program prog with arguments
1224 args . The new process executes concurrently with the current process.
1225 The standard output of the new process is redirected to a pipe, which
1226 can be read via the returned input channel.
1227 The executable file prog is searched in the path. This behaviour
1229 changed in 4.12; previously prog was looked up only in the current di‐
1230 rectory.
1231 The new process has the same environment as the current process.
1233 Since 4.08.0
1236 val open_process_args_out : string -> string array -> out_channel
1240 Same as UnixLabels.open_process_args_in , but redirect the standard in‐
1242 put of the new process to a pipe. Data written to the returned output
1243 channel is sent to the standard input of the program. Warning: writes
1244 on output channels are buffered, hence be careful to call flush at the
1245 right times to ensure correct synchronization.
1246 Since 4.08.0
1249 val open_process_args : string -> string array -> in_channel *
1253 out_channel
1254 Same as UnixLabels.open_process_args_out , but redirects both the stan‐
1256 dard input and standard output of the new process to pipes connected to
1257 the two returned channels. The input channel is connected to the out‐
1258 put of the program, and the output channel to the input of the program.
1259 Since 4.08.0
1262 val open_process_args_full : string -> string array -> string array ->
1266 in_channel * out_channel * in_channel
1267 Similar to UnixLabels.open_process_args , but the third argument speci‐
1269 fies the environment passed to the new process. The result is a triple
1270 of channels connected respectively to the standard output, standard in‐
1271 put, and standard error of the program.
1272 Since 4.08.0
1275 val process_in_pid : in_channel -> int
1279 Return the pid of a process opened via UnixLabels.open_process_in or
1281 UnixLabels.open_process_args_in .
1282 Since 4.12.0
1285 val process_out_pid : out_channel -> int
1289 Return the pid of a process opened via UnixLabels.open_process_out or
1291 UnixLabels.open_process_args_out .
1292 Since 4.12.0
1295 val process_pid : in_channel * out_channel -> int
1299 Return the pid of a process opened via UnixLabels.open_process or
1301 UnixLabels.open_process_args .
1302 Since 4.12.0
1305 val process_full_pid : in_channel * out_channel * in_channel -> int
1309 Return the pid of a process opened via UnixLabels.open_process_full or
1311 UnixLabels.open_process_args_full .
1312 Since 4.12.0
1315 val close_process_in : in_channel -> process_status
1319 Close channels opened by UnixLabels.open_process_in , wait for the as‐
1321 sociated command to terminate, and return its termination status.
1322 val close_process_out : out_channel -> process_status
1326 Close channels opened by UnixLabels.open_process_out , wait for the as‐
1328 sociated command to terminate, and return its termination status.
1329 val close_process : in_channel * out_channel -> process_status
1333 Close channels opened by UnixLabels.open_process , wait for the associ‐
1335 ated command to terminate, and return its termination status.
1336 val close_process_full : in_channel * out_channel * in_channel ->
1340 process_status
1341 Close channels opened by UnixLabels.open_process_full , wait for the
1343 associated command to terminate, and return its termination status.
1344 Symbolic links
1349 val symlink : ?to_dir:bool -> src:string -> dst:string -> unit
1350 symlink ?to_dir ~src ~dst creates the file dst as a symbolic link to
1353 the file src . On Windows, ~to_dir indicates if the symbolic link
1354 points to a directory or a file; if omitted, symlink examines src using
1355 stat and picks appropriately, if src does not exist then false is as‐
1356 sumed (for this reason, it is recommended that the ~to_dir parameter be
1357 specified in new code). On Unix, ~to_dir is ignored.
1358 Windows symbolic links are available in Windows Vista onwards. There
1360 are some important differences between Windows symlinks and their POSIX
1361 counterparts.
1362 Windows symbolic links come in two flavours: directory and regular,
1364 which designate whether the symbolic link points to a directory or a
1365 file. The type must be correct - a directory symlink which actually
1366 points to a file cannot be selected with chdir and a file symlink which
1367 actually points to a directory cannot be read or written (note that
1368 Cygwin's emulation layer ignores this distinction).
1369 When symbolic links are created to existing targets, this distinction
1371 doesn't matter and symlink will automatically create the correct kind
1372 of symbolic link. The distinction matters when a symbolic link is cre‐
1373 ated to a non-existent target.
1374 The other caveat is that by default symbolic links are a privileged op‐
1376 eration. Administrators will always need to be running elevated (or
1377 with UAC disabled) and by default normal user accounts need to be
1378 granted the SeCreateSymbolicLinkPrivilege via Local Security Policy
1379 (secpol.msc) or via Active Directory.
1380 UnixLabels.has_symlink can be used to check that a process is able to
1383 create symbolic links.
1384 val has_symlink : unit -> bool
1388 Returns true if the user is able to create symbolic links. On Windows,
1390 this indicates that the user not only has the SeCreateSymbolicLinkPriv‐
1391 ilege but is also running elevated, if necessary. On other platforms,
1392 this is simply indicates that the symlink system call is available.
1393 Since 4.03.0
1396 val readlink : string -> string
1400 Read the contents of a symbolic link.
1402 Polling
1407 val select : read:file_descr list -> write:file_descr list -> ex‐
1408 cept:file_descr list -> timeout:float -> file_descr list * file_descr
1409 list * file_descr list
1410 Wait until some input/output operations become possible on some chan‐
1412 nels. The three list arguments are, respectively, a set of descriptors
1413 to check for reading (first argument), for writing (second argument),
1414 or for exceptional conditions (third argument). The fourth argument is
1415 the maximal timeout, in seconds; a negative fourth argument means no
1416 timeout (unbounded wait). The result is composed of three sets of de‐
1417 scriptors: those ready for reading (first component), ready for writing
1418 (second component), and over which an exceptional condition is pending
1419 (third component).
1420 Locking
1425 type lock_command = Unix.lock_command =
1426 | F_ULOCK (* Unlock a region
1427 *)
1428 | F_LOCK (* Lock a region for writing, and block if already locked
1429 *)
1430 | F_TLOCK (* Lock a region for writing, or fail if already locked
1431 *)
1432 | F_TEST (* Test a region for other process locks
1433 *)
1434 | F_RLOCK (* Lock a region for reading, and block if already locked
1435 *)
1436 | F_TRLOCK (* Lock a region for reading, or fail if already locked
1437 *)
1438 Commands for UnixLabels.lockf .
1441 val lockf : file_descr -> mode:lock_command -> len:int -> unit
1445 lockf fd ~mode ~len puts a lock on a region of the file opened as fd .
1448 The region starts at the current read/write position for fd (as set by
1449 UnixLabels.lseek ), and extends len bytes forward if len is positive,
1450 len bytes backwards if len is negative, or to the end of the file if
1451 len is zero. A write lock prevents any other process from acquiring a
1452 read or write lock on the region. A read lock prevents any other
1453 process from acquiring a write lock on the region, but lets other pro‐
1454 cesses acquire read locks on it.
1455 The F_LOCK and F_TLOCK commands attempts to put a write lock on the
1457 specified region. The F_RLOCK and F_TRLOCK commands attempts to put a
1458 read lock on the specified region. If one or several locks put by an‐
1459 other process prevent the current process from acquiring the lock,
1460 F_LOCK and F_RLOCK block until these locks are removed, while F_TLOCK
1461 and F_TRLOCK fail immediately with an exception. The F_ULOCK removes
1462 whatever locks the current process has on the specified region. Fi‐
1463 nally, the F_TEST command tests whether a write lock can be acquired on
1464 the specified region, without actually putting a lock. It returns im‐
1465 mediately if successful, or fails otherwise.
1466 What happens when a process tries to lock a region of a file that is
1468 already locked by the same process depends on the OS. On POSIX-compli‐
1469 ant systems, the second lock operation succeeds and may "promote" the
1470 older lock from read lock to write lock. On Windows, the second lock
1471 operation will block or fail.
1472 Signals
1477 Note: installation of signal handlers is performed via the functions
1478 Sys.signal and Sys.set_signal .
1479 val kill : pid:int -> signal:int -> unit
1481 kill ~pid ~signal sends signal number signal to the process with id pid
1484 .
1485 On Windows: only the Sys.sigkill signal is emulated.
1487 type sigprocmask_command = Unix.sigprocmask_command =
1490 | SIG_SETMASK
1491 | SIG_BLOCK
1492 | SIG_UNBLOCK
1493 val sigprocmask : mode:sigprocmask_command -> int list -> int list
1499 sigprocmask ~mode sigs changes the set of blocked signals. If mode is
1502 SIG_SETMASK , blocked signals are set to those in the list sigs . If
1503 mode is SIG_BLOCK , the signals in sigs are added to the set of blocked
1504 signals. If mode is SIG_UNBLOCK , the signals in sigs are removed from
1505 the set of blocked signals. sigprocmask returns the set of previously
1506 blocked signals.
1507 When the systhreads version of the Thread module is loaded, this func‐
1509 tion redirects to Thread.sigmask . I.e., sigprocmask only changes the
1510 mask of the current thread.
1511 Raises Invalid_argument on Windows (no inter-process signals on Win‐
1514 dows)
1515 val sigpending : unit -> int list
1519 Return the set of blocked signals that are currently pending.
1521 Raises Invalid_argument on Windows (no inter-process signals on Win‐
1524 dows)
1525 val sigsuspend : int list -> unit
1529 sigsuspend sigs atomically sets the blocked signals to sigs and waits
1532 for a non-ignored, non-blocked signal to be delivered. On return, the
1533 blocked signals are reset to their initial value.
1534 Raises Invalid_argument on Windows (no inter-process signals on Win‐
1537 dows)
1538 val pause : unit -> unit
1542 Wait until a non-ignored, non-blocked signal is delivered.
1544 Raises Invalid_argument on Windows (no inter-process signals on Win‐
1547 dows)
1548 Time functions
1553 type process_times = Unix.process_times = {
1554 tms_utime : float ; (* User time for the process
1555 *)
1556 tms_stime : float ; (* System time for the process
1557 *)
1558 tms_cutime : float ; (* User time for the children processes
1559 *)
1560 tms_cstime : float ; (* System time for the children processes
1561 *)
1562 }
1563 The execution times (CPU times) of a process.
1566 type tm = Unix.tm = {
1569 tm_sec : int ; (* Seconds 0..60
1570 *)
1571 tm_min : int ; (* Minutes 0..59
1572 *)
1573 tm_hour : int ; (* Hours 0..23
1574 *)
1575 tm_mday : int ; (* Day of month 1..31
1576 *)
1577 tm_mon : int ; (* Month of year 0..11
1578 *)
1579 tm_year : int ; (* Year - 1900
1580 *)
1581 tm_wday : int ; (* Day of week (Sunday is 0)
1582 *)
1583 tm_yday : int ; (* Day of year 0..365
1584 *)
1585 tm_isdst : bool ; (* Daylight time savings in effect
1586 *)
1587 }
1588 The type representing wallclock time and calendar date.
1591 val time : unit -> float
1595 Return the current time since 00:00:00 GMT, Jan. 1, 1970, in seconds.
1597 val gettimeofday : unit -> float
1601 Same as UnixLabels.time , but with resolution better than 1 second.
1603 val gmtime : float -> tm
1607 Convert a time in seconds, as returned by UnixLabels.time , into a date
1609 and a time. Assumes UTC (Coordinated Universal Time), also known as
1610 GMT. To perform the inverse conversion, set the TZ environment vari‐
1611 able to "UTC", use UnixLabels.mktime , and then restore the original
1612 value of TZ.
1613 val localtime : float -> tm
1617 Convert a time in seconds, as returned by UnixLabels.time , into a date
1619 and a time. Assumes the local time zone. The function performing the
1620 inverse conversion is UnixLabels.mktime .
1621 val mktime : tm -> float * tm
1625 Convert a date and time, specified by the tm argument, into a time in
1627 seconds, as returned by UnixLabels.time . The tm_isdst , tm_wday and
1628 tm_yday fields of tm are ignored. Also return a normalized copy of the
1629 given tm record, with the tm_wday , tm_yday , and tm_isdst fields re‐
1630 computed from the other fields, and the other fields normalized (so
1631 that, e.g., 40 October is changed into 9 November). The tm argument is
1632 interpreted in the local time zone.
1633 val alarm : int -> int
1637 Schedule a SIGALRM signal after the given number of seconds.
1639 Raises Invalid_argument on Windows
1642 val sleep : int -> unit
1646 Stop execution for the given number of seconds.
1648 val sleepf : float -> unit
1652 Stop execution for the given number of seconds. Like sleep , but frac‐
1654 tions of seconds are supported.
1655 Since 4.12.0
1658 val times : unit -> process_times
1662 Return the execution times of the process.
1664 On Windows: partially implemented, will not report timings for child
1666 processes.
1667 val utimes : string -> access:float -> modif:float -> unit
1671 Set the last access time (second arg) and last modification time (third
1673 arg) for a file. Times are expressed in seconds from 00:00:00 GMT, Jan.
1674 1, 1970. If both times are 0.0 , the access and last modification
1675 times are both set to the current time.
1676 type interval_timer = Unix.interval_timer =
1679 | ITIMER_REAL (* decrements in real time, and sends the signal
1680 SIGALRM when expired.
1681 *)
1682 | ITIMER_VIRTUAL (* decrements in process virtual time, and sends
1683 SIGVTALRM when expired.
1684 *)
1685 | ITIMER_PROF (* (for profiling) decrements both when the process is
1686 running and when the system is running on behalf of the process; it
1687 sends SIGPROF when expired.
1688 *)
1689 The three kinds of interval timers.
1692 type interval_timer_status = Unix.interval_timer_status = {
1695 it_interval : float ; (* Period
1696 *)
1697 it_value : float ; (* Current value of the timer
1698 *)
1699 }
1700 The type describing the status of an interval timer
1703 val getitimer : interval_timer -> interval_timer_status
1707 Return the current status of the given interval timer.
1709 Raises Invalid_argument on Windows
1712 val setitimer : interval_timer -> interval_timer_status -> inter‐
1716 val_timer_status
1717 setitimer t s sets the interval timer t and returns its previous sta‐
1720 tus. The s argument is interpreted as follows: s.it_value , if nonzero,
1721 is the time to the next timer expiration; s.it_interval , if nonzero,
1722 specifies a value to be used in reloading it_value when the timer ex‐
1723 pires. Setting s.it_value to zero disables the timer. Setting
1724 s.it_interval to zero causes the timer to be disabled after its next
1725 expiration.
1726 Raises Invalid_argument on Windows
1729 User id, group id
1734 val getuid : unit -> int
1735 Return the user id of the user executing the process.
1737 On Windows: always returns 1 .
1739 val geteuid : unit -> int
1743 Return the effective user id under which the process runs.
1745 On Windows: always returns 1 .
1747 val setuid : int -> unit
1751 Set the real user id and effective user id for the process.
1753 Raises Invalid_argument on Windows
1756 val getgid : unit -> int
1760 Return the group id of the user executing the process.
1762 On Windows: always returns 1 .
1764 val getegid : unit -> int
1768 Return the effective group id under which the process runs.
1770 On Windows: always returns 1 .
1772 val setgid : int -> unit
1776 Set the real group id and effective group id for the process.
1778 Raises Invalid_argument on Windows
1781 val getgroups : unit -> int array
1785 Return the list of groups to which the user executing the process be‐
1787 longs.
1788 On Windows: always returns [|1|] .
1790 val setgroups : int array -> unit
1794 setgroups groups sets the supplementary group IDs for the calling
1797 process. Appropriate privileges are required.
1798 Raises Invalid_argument on Windows
1801 val initgroups : string -> int -> unit
1805 initgroups user group initializes the group access list by reading the
1808 group database /etc/group and using all groups of which user is a mem‐
1809 ber. The additional group group is also added to the list.
1810 Raises Invalid_argument on Windows
1813 type passwd_entry = Unix.passwd_entry = {
1816 pw_name : string ;
1817 pw_passwd : string ;
1818 pw_uid : int ;
1819 pw_gid : int ;
1820 pw_gecos : string ;
1821 pw_dir : string ;
1822 pw_shell : string ;
1823 }
1824 Structure of entries in the passwd database.
1827 type group_entry = Unix.group_entry = {
1830 gr_name : string ;
1831 gr_passwd : string ;
1832 gr_gid : int ;
1833 gr_mem : string array ;
1834 }
1835 Structure of entries in the groups database.
1838 val getlogin : unit -> string
1842 Return the login name of the user executing the process.
1844 val getpwnam : string -> passwd_entry
1848 Find an entry in passwd with the given name.
1850 Raises Not_found if no such entry exists, or always on Windows.
1853 val getgrnam : string -> group_entry
1857 Find an entry in group with the given name.
1859 Raises Not_found if no such entry exists, or always on Windows.
1862 val getpwuid : int -> passwd_entry
1866 Find an entry in passwd with the given user id.
1868 Raises Not_found if no such entry exists, or always on Windows.
1871 val getgrgid : int -> group_entry
1875 Find an entry in group with the given group id.
1877 Raises Not_found if no such entry exists, or always on Windows.
1880 Internet addresses
1885 type inet_addr = Unix.inet_addr
1886 The abstract type of Internet addresses.
1889 val inet_addr_of_string : string -> inet_addr
1893 Conversion from the printable representation of an Internet address to
1895 its internal representation. The argument string consists of 4 numbers
1896 separated by periods ( XXX.YYY.ZZZ.TTT ) for IPv4 addresses, and up to
1897 8 numbers separated by colons for IPv6 addresses.
1898 Raises Failure when given a string that does not match these formats.
1901 val string_of_inet_addr : inet_addr -> string
1905 Return the printable representation of the given Internet address. See
1907 UnixLabels.inet_addr_of_string for a description of the printable rep‐
1908 resentation.
1909 val inet_addr_any : inet_addr
1913 A special IPv4 address, for use only with bind , representing all the
1915 Internet addresses that the host machine possesses.
1916 val inet_addr_loopback : inet_addr
1920 A special IPv4 address representing the host machine ( 127.0.0.1 ).
1922 val inet6_addr_any : inet_addr
1926 A special IPv6 address, for use only with bind , representing all the
1928 Internet addresses that the host machine possesses.
1929 val inet6_addr_loopback : inet_addr
1933 A special IPv6 address representing the host machine ( ::1 ).
1935 val is_inet6_addr : inet_addr -> bool
1939 Whether the given inet_addr is an IPv6 address.
1941 Since 4.12.0
1944 Sockets
1949 type socket_domain = Unix.socket_domain =
1950 | PF_UNIX (* Unix domain
1951 *)
1952 | PF_INET (* Internet domain (IPv4)
1953 *)
1954 | PF_INET6 (* Internet domain (IPv6)
1955 *)
1956 The type of socket domains. Not all platforms support IPv6 sockets
1959 (type PF_INET6 ).
1960 On Windows: PF_UNIX supported since 4.14.0 on Windows 10 1803 and
1962 later.
1963 type socket_type = Unix.socket_type =
1966 | SOCK_STREAM (* Stream socket
1967 *)
1968 | SOCK_DGRAM (* Datagram socket
1969 *)
1970 | SOCK_RAW (* Raw socket
1971 *)
1972 | SOCK_SEQPACKET (* Sequenced packets socket
1973 *)
1974 The type of socket kinds, specifying the semantics of communications.
1977 SOCK_SEQPACKET is included for completeness, but is rarely supported by
1978 the OS, and needs system calls that are not available in this library.
1979 type sockaddr = Unix.sockaddr =
1982 | ADDR_UNIX of string
1983 | ADDR_INET of inet_addr * int
1984 The type of socket addresses. ADDR_UNIX name is a socket address in
1987 the Unix domain; name is a file name in the file system.
1988 ADDR_INET(addr,port) is a socket address in the Internet domain; addr
1989 is the Internet address of the machine, and port is the port number.
1990 val socket : ?cloexec:bool -> domain:socket_domain -> kind:socket_type
1994 -> protocol:int -> file_descr
1995 Create a new socket in the given domain, and with the given kind. The
1997 third argument is the protocol type; 0 selects the default protocol for
1998 that kind of sockets. See UnixLabels.set_close_on_exec for documenta‐
1999 tion on the cloexec optional argument.
2000 val domain_of_sockaddr : sockaddr -> socket_domain
2004 Return the socket domain adequate for the given socket address.
2006 val socketpair : ?cloexec:bool -> domain:socket_domain ->
2010 kind:socket_type -> protocol:int -> file_descr * file_descr
2011 Create a pair of unnamed sockets, connected together. See UnixLa‐
2013 bels.set_close_on_exec for documentation on the cloexec optional argu‐
2014 ment.
2015 Raises Invalid_argument on Windows
2018 val accept : ?cloexec:bool -> file_descr -> file_descr * sockaddr
2022 Accept connections on the given socket. The returned descriptor is a
2024 socket connected to the client; the returned address is the address of
2025 the connecting client. See UnixLabels.set_close_on_exec for documenta‐
2026 tion on the cloexec optional argument.
2027 val bind : file_descr -> addr:sockaddr -> unit
2031 Bind a socket to an address.
2033 val connect : file_descr -> addr:sockaddr -> unit
2037 Connect a socket to an address.
2039 val listen : file_descr -> max:int -> unit
2043 Set up a socket for receiving connection requests. The integer argument
2045 is the maximal number of pending requests.
2046 type shutdown_command = Unix.shutdown_command =
2049 | SHUTDOWN_RECEIVE (* Close for receiving
2050 *)
2051 | SHUTDOWN_SEND (* Close for sending
2052 *)
2053 | SHUTDOWN_ALL (* Close both
2054 *)
2055 The type of commands for shutdown .
2058 val shutdown : file_descr -> mode:shutdown_command -> unit
2062 Shutdown a socket connection. SHUTDOWN_SEND as second argument causes
2064 reads on the other end of the connection to return an end-of-file con‐
2065 dition. SHUTDOWN_RECEIVE causes writes on the other end of the connec‐
2066 tion to return a closed pipe condition ( SIGPIPE signal).
2067 val getsockname : file_descr -> sockaddr
2071 Return the address of the given socket.
2073 val getpeername : file_descr -> sockaddr
2077 Return the address of the host connected to the given socket.
2079 type msg_flag = Unix.msg_flag =
2082 | MSG_OOB
2083 | MSG_DONTROUTE
2084 | MSG_PEEK
2085 The flags for UnixLabels.recv , UnixLabels.recvfrom , UnixLabels.send
2088 and UnixLabels.sendto .
2089 val recv : file_descr -> buf:bytes -> pos:int -> len:int ->
2093 mode:msg_flag list -> int
2094 Receive data from a connected socket.
2096 val recvfrom : file_descr -> buf:bytes -> pos:int -> len:int ->
2100 mode:msg_flag list -> int * sockaddr
2101 Receive data from an unconnected socket.
2103 val send : file_descr -> buf:bytes -> pos:int -> len:int ->
2107 mode:msg_flag list -> int
2108 Send data over a connected socket.
2110 val send_substring : file_descr -> buf:string -> pos:int -> len:int ->
2114 mode:msg_flag list -> int
2115 Same as send , but take the data from a string instead of a byte se‐
2117 quence.
2118 Since 4.02.0
2121 val sendto : file_descr -> buf:bytes -> pos:int -> len:int ->
2125 mode:msg_flag list -> addr:sockaddr -> int
2126 Send data over an unconnected socket.
2128 val sendto_substring : file_descr -> buf:string -> pos:int -> len:int
2132 -> mode:msg_flag list -> sockaddr -> int
2133 Same as sendto , but take the data from a string instead of a byte se‐
2135 quence.
2136 Since 4.02.0
2139 Socket options
2144 type socket_bool_option = Unix.socket_bool_option =
2145 | SO_DEBUG (* Record debugging information
2146 *)
2147 | SO_BROADCAST (* Permit sending of broadcast messages
2148 *)
2149 | SO_REUSEADDR (* Allow reuse of local addresses for bind
2150 *)
2151 | SO_KEEPALIVE (* Keep connection active
2152 *)
2153 | SO_DONTROUTE (* Bypass the standard routing algorithms
2154 *)
2155 | SO_OOBINLINE (* Leave out-of-band data in line
2156 *)
2157 | SO_ACCEPTCONN (* Report whether socket listening is enabled
2158 *)
2159 | TCP_NODELAY (* Control the Nagle algorithm for TCP sockets
2160 *)
2161 | IPV6_ONLY (* Forbid binding an IPv6 socket to an IPv4 address
2162 *)
2163 | SO_REUSEPORT (* Allow reuse of address and port bindings
2164 *)
2165 The socket options that can be consulted with UnixLabels.getsockopt and
2168 modified with UnixLabels.setsockopt . These options have a boolean (
2169 true / false ) value.
2170 type socket_int_option = Unix.socket_int_option =
2173 | SO_SNDBUF (* Size of send buffer
2174 *)
2175 | SO_RCVBUF (* Size of received buffer
2176 *)
2177 | SO_ERROR (* Deprecated. Use UnixLabels.getsockopt_error instead.
2178 *)
2179 | SO_TYPE (* Report the socket type
2180 *)
2181 | SO_RCVLOWAT (* Minimum number of bytes to process for input opera‐
2182 tions
2183 *)
2184 | SO_SNDLOWAT (* Minimum number of bytes to process for output opera‐
2185 tions
2186 *)
2187 The socket options that can be consulted with UnixLabels.getsockopt_int
2190 and modified with UnixLabels.setsockopt_int . These options have an
2191 integer value.
2192 type socket_optint_option = Unix.socket_optint_option =
2195 | SO_LINGER (* Whether to linger on closed connections that have data
2196 present, and for how long (in seconds)
2197 *)
2198 The socket options that can be consulted with UnixLabels.getsock‐
2201 opt_optint and modified with UnixLabels.setsockopt_optint . These op‐
2202 tions have a value of type int option , with None meaning ``disabled''.
2203 type socket_float_option = Unix.socket_float_option =
2206 | SO_RCVTIMEO (* Timeout for input operations
2207 *)
2208 | SO_SNDTIMEO (* Timeout for output operations
2209 *)
2210 The socket options that can be consulted with UnixLabels.getsock‐
2213 opt_float and modified with UnixLabels.setsockopt_float . These op‐
2214 tions have a floating-point value representing a time in seconds. The
2215 value 0 means infinite timeout.
2216 val getsockopt : file_descr -> socket_bool_option -> bool
2220 Return the current status of a boolean-valued option in the given
2222 socket.
2223 val setsockopt : file_descr -> socket_bool_option -> bool -> unit
2227 Set or clear a boolean-valued option in the given socket.
2229 val getsockopt_int : file_descr -> socket_int_option -> int
2233 Same as UnixLabels.getsockopt for an integer-valued socket option.
2235 val setsockopt_int : file_descr -> socket_int_option -> int -> unit
2239 Same as UnixLabels.setsockopt for an integer-valued socket option.
2241 val getsockopt_optint : file_descr -> socket_optint_option -> int op‐
2245 tion
2246 Same as UnixLabels.getsockopt for a socket option whose value is an int
2248 option .
2249 val setsockopt_optint : file_descr -> socket_optint_option -> int op‐
2253 tion -> unit
2254 Same as UnixLabels.setsockopt for a socket option whose value is an int
2256 option .
2257 val getsockopt_float : file_descr -> socket_float_option -> float
2261 Same as UnixLabels.getsockopt for a socket option whose value is a
2263 floating-point number.
2264 val setsockopt_float : file_descr -> socket_float_option -> float ->
2268 unit
2269 Same as UnixLabels.setsockopt for a socket option whose value is a
2271 floating-point number.
2272 val getsockopt_error : file_descr -> error option
2276 Return the error condition associated with the given socket, and clear
2278 it.
2279 High-level network connection functions
2284 val open_connection : sockaddr -> in_channel * out_channel
2285 Connect to a server at the given address. Return a pair of buffered
2287 channels connected to the server. Remember to call flush on the output
2288 channel at the right times to ensure correct synchronization.
2289 The two channels returned by open_connection share a descriptor to a
2291 socket. Therefore, when the connection is over, you should call
2292 close_out on the output channel, which will also close the underlying
2293 socket. Do not call close_in on the input channel; it will be col‐
2294 lected by the GC eventually.
2295 val shutdown_connection : in_channel -> unit
2299 ``Shut down'' a connection established with UnixLabels.open_connection
2301 ; that is, transmit an end-of-file condition to the server reading on
2302 the other side of the connection. This does not close the socket and
2303 the channels used by the connection. See Unix.open_connection for how
2304 to close them once the connection is over.
2305 val establish_server : (in_channel -> out_channel -> unit) ->
2309 addr:sockaddr -> unit
2310 Establish a server on the given address. The function given as first
2312 argument is called for each connection with two buffered channels con‐
2313 nected to the client. A new process is created for each connection. The
2314 function UnixLabels.establish_server never returns normally.
2315 The two channels given to the function share a descriptor to a socket.
2317 The function does not need to close the channels, since this occurs au‐
2318 tomatically when the function returns. If the function prefers ex‐
2319 plicit closing, it should close the output channel using close_out and
2320 leave the input channel unclosed, for reasons explained in
2321 Unix.in_channel_of_descr .
2322 Raises Invalid_argument on Windows. Use threads instead.
2325 Host and protocol databases
2330 type host_entry = Unix.host_entry = {
2331 h_name : string ;
2332 h_aliases : string array ;
2333 h_addrtype : socket_domain ;
2334 h_addr_list : inet_addr array ;
2335 }
2336 Structure of entries in the hosts database.
2339 type protocol_entry = Unix.protocol_entry = {
2342 p_name : string ;
2343 p_aliases : string array ;
2344 p_proto : int ;
2345 }
2346 Structure of entries in the protocols database.
2349 type service_entry = Unix.service_entry = {
2352 s_name : string ;
2353 s_aliases : string array ;
2354 s_port : int ;
2355 s_proto : string ;
2356 }
2357 Structure of entries in the services database.
2360 val gethostname : unit -> string
2364 Return the name of the local host.
2366 val gethostbyname : string -> host_entry
2370 Find an entry in hosts with the given name.
2372 Raises Not_found if no such entry exists.
2375 val gethostbyaddr : inet_addr -> host_entry
2379 Find an entry in hosts with the given address.
2381 Raises Not_found if no such entry exists.
2384 val getprotobyname : string -> protocol_entry
2388 Find an entry in protocols with the given name.
2390 Raises Not_found if no such entry exists.
2393 val getprotobynumber : int -> protocol_entry
2397 Find an entry in protocols with the given protocol number.
2399 Raises Not_found if no such entry exists.
2402 val getservbyname : string -> protocol:string -> service_entry
2406 Find an entry in services with the given name.
2408 Raises Not_found if no such entry exists.
2411 val getservbyport : int -> protocol:string -> service_entry
2415 Find an entry in services with the given service number.
2417 Raises Not_found if no such entry exists.
2420 type addr_info = Unix.addr_info = {
2423 ai_family : socket_domain ; (* Socket domain
2424 *)
2425 ai_socktype : socket_type ; (* Socket type
2426 *)
2427 ai_protocol : int ; (* Socket protocol number
2428 *)
2429 ai_addr : sockaddr ; (* Address
2430 *)
2431 ai_canonname : string ; (* Canonical host name
2432 *)
2433 }
2434 Address information returned by UnixLabels.getaddrinfo .
2437 type getaddrinfo_option = Unix.getaddrinfo_option =
2440 | AI_FAMILY of socket_domain
2441 (* Impose the given socket domain
2442 *)
2443 | AI_SOCKTYPE of socket_type
2444 (* Impose the given socket type
2445 *)
2446 | AI_PROTOCOL of int
2447 (* Impose the given protocol
2448 *)
2449 | AI_NUMERICHOST (* Do not call name resolver, expect numeric IP ad‐
2450 dress
2451 *)
2452 | AI_CANONNAME (* Fill the ai_canonname field of the result
2453 *)
2454 | AI_PASSIVE (* Set address to ``any'' address for use with UnixLa‐
2455 bels.bind
2456 *)
2458 Options to UnixLabels.getaddrinfo .
2461 val getaddrinfo : string -> string -> getaddrinfo_option list ->
2465 addr_info list
2466 getaddrinfo host service opts returns a list of UnixLabels.addr_info
2469 records describing socket parameters and addresses suitable for commu‐
2470 nicating with the given host and service. The empty list is returned
2471 if the host or service names are unknown, or the constraints expressed
2472 in opts cannot be satisfied.
2473 host is either a host name or the string representation of an IP ad‐
2476 dress. host can be given as the empty string; in this case, the
2477 ``any'' address or the ``loopback'' address are used, depending whether
2478 opts contains AI_PASSIVE . service is either a service name or the
2479 string representation of a port number. service can be given as the
2480 empty string; in this case, the port field of the returned addresses is
2481 set to 0. opts is a possibly empty list of options that allows the
2482 caller to force a particular socket domain (e.g. IPv6 only or IPv4
2483 only) or a particular socket type (e.g. TCP only or UDP only).
2484 type name_info = Unix.name_info = {
2487 ni_hostname : string ; (* Name or IP address of host
2488 *)
2489 ni_service : string ; (* Name of service or port number
2490 *)
2491 }
2492 Host and service information returned by UnixLabels.getnameinfo .
2495 type getnameinfo_option = Unix.getnameinfo_option =
2498 | NI_NOFQDN (* Do not qualify local host names
2499 *)
2500 | NI_NUMERICHOST (* Always return host as IP address
2501 *)
2502 | NI_NAMEREQD (* Fail if host name cannot be determined
2503 *)
2504 | NI_NUMERICSERV (* Always return service as port number
2505 *)
2506 | NI_DGRAM (* Consider the service as UDP-based instead of the de‐
2507 fault TCP
2508 *)
2509 Options to UnixLabels.getnameinfo .
2512 val getnameinfo : sockaddr -> getnameinfo_option list -> name_info
2516 getnameinfo addr opts returns the host name and service name corre‐
2519 sponding to the socket address addr . opts is a possibly empty list of
2520 options that governs how these names are obtained.
2521 Raises Not_found if an error occurs.
2524 Terminal interface
2529 The following functions implement the POSIX standard terminal inter‐
2530 face. They provide control over asynchronous communication ports and
2531 pseudo-terminals. Refer to the termios man page for a complete descrip‐
2532 tion.
2533 type terminal_io = Unix.terminal_io = {
2535 mutable c_ignbrk : bool ; (* Ignore the break condition.
2537 *)
2538 mutable c_brkint : bool ; (* Signal interrupt on break condition.
2540 *)
2541 mutable c_ignpar : bool ; (* Ignore characters with parity errors.
2543 *)
2544 mutable c_parmrk : bool ; (* Mark parity errors.
2546 *)
2547 mutable c_inpck : bool ; (* Enable parity check on input.
2549 *)
2550 mutable c_istrip : bool ; (* Strip 8th bit on input characters.
2552 *)
2553 mutable c_inlcr : bool ; (* Map NL to CR on input.
2555 *)
2556 mutable c_igncr : bool ; (* Ignore CR on input.
2558 *)
2559 mutable c_icrnl : bool ; (* Map CR to NL on input.
2561 *)
2562 mutable c_ixon : bool ; (* Recognize XON/XOFF characters on input.
2564 *)
2565 mutable c_ixoff : bool ; (* Emit XON/XOFF chars to control input flow.
2567 *)
2568 mutable c_opost : bool ; (* Enable output processing.
2570 *)
2571 mutable c_obaud : int ; (* Output baud rate (0 means close connec‐
2573 tion).
2574 *)
2575 mutable c_ibaud : int ; (* Input baud rate.
2577 *)
2578 mutable c_csize : int ; (* Number of bits per character (5-8).
2580 *)
2581 mutable c_cstopb : int ; (* Number of stop bits (1-2).
2583 *)
2584 mutable c_cread : bool ; (* Reception is enabled.
2586 *)
2587 mutable c_parenb : bool ; (* Enable parity generation and detection.
2589 *)
2590 mutable c_parodd : bool ; (* Specify odd parity instead of even.
2592 *)
2593 mutable c_hupcl : bool ; (* Hang up on last close.
2595 *)
2596 mutable c_clocal : bool ; (* Ignore modem status lines.
2598 *)
2599 mutable c_isig : bool ; (* Generate signal on INTR, QUIT, SUSP.
2601 *)
2602 mutable c_icanon : bool ; (* Enable canonical processing (line buffer‐
2604 ing and editing)
2605 *)
2606 mutable c_noflsh : bool ; (* Disable flush after INTR, QUIT, SUSP.
2608 *)
2609 mutable c_echo : bool ; (* Echo input characters.
2611 *)
2612 mutable c_echoe : bool ; (* Echo ERASE (to erase previous character).
2614 *)
2615 mutable c_echok : bool ; (* Echo KILL (to erase the current line).
2617 *)
2618 mutable c_echonl : bool ; (* Echo NL even if c_echo is not set.
2620 *)
2621 mutable c_vintr : char ; (* Interrupt character (usually ctrl-C).
2623 *)
2624 mutable c_vquit : char ; (* Quit character (usually ctrl-\).
2626 *)
2627 mutable c_verase : char ; (* Erase character (usually DEL or ctrl-H).
2629 *)
2630 mutable c_vkill : char ; (* Kill line character (usually ctrl-U).
2632 *)
2633 mutable c_veof : char ; (* End-of-file character (usually ctrl-D).
2635 *)
2636 mutable c_veol : char ; (* Alternate end-of-line char. (usually none).
2638 *)
2639 mutable c_vmin : int ; (* Minimum number of characters to read before
2641 the read request is satisfied.
2642 *)
2643 mutable c_vtime : int ; (* Maximum read wait (in 0.1s units).
2645 *)
2646 mutable c_vstart : char ; (* Start character (usually ctrl-Q).
2648 *)
2649 mutable c_vstop : char ; (* Stop character (usually ctrl-S).
2651 *)
2652 }
2653 val tcgetattr : file_descr -> terminal_io
2659 Return the status of the terminal referred to by the given file de‐
2661 scriptor.
2662 Raises Invalid_argument on Windows
2665 type setattr_when = Unix.setattr_when =
2668 | TCSANOW
2669 | TCSADRAIN
2670 | TCSAFLUSH
2671 val tcsetattr : file_descr -> mode:setattr_when -> terminal_io -> unit
2677 Set the status of the terminal referred to by the given file descrip‐
2679 tor. The second argument indicates when the status change takes place:
2680 immediately ( TCSANOW ), when all pending output has been transmitted (
2681 TCSADRAIN ), or after flushing all input that has been received but not
2682 read ( TCSAFLUSH ). TCSADRAIN is recommended when changing the output
2683 parameters; TCSAFLUSH , when changing the input parameters.
2684 Raises Invalid_argument on Windows
2687 val tcsendbreak : file_descr -> duration:int -> unit
2691 Send a break condition on the given file descriptor. The second argu‐
2693 ment is the duration of the break, in 0.1s units; 0 means standard du‐
2694 ration (0.25s).
2695 Raises Invalid_argument on Windows
2698 val tcdrain : file_descr -> unit
2702 Waits until all output written on the given file descriptor has been
2704 transmitted.
2705 Raises Invalid_argument on Windows
2708 type flush_queue = Unix.flush_queue =
2711 | TCIFLUSH
2712 | TCOFLUSH
2713 | TCIOFLUSH
2714 val tcflush : file_descr -> mode:flush_queue -> unit
2720 Discard data written on the given file descriptor but not yet transmit‐
2722 ted, or data received but not yet read, depending on the second argu‐
2723 ment: TCIFLUSH flushes data received but not read, TCOFLUSH flushes
2724 data written but not transmitted, and TCIOFLUSH flushes both.
2725 Raises Invalid_argument on Windows
2728 type flow_action = Unix.flow_action =
2731 | TCOOFF
2732 | TCOON
2733 | TCIOFF
2734 | TCION
2735 val tcflow : file_descr -> mode:flow_action -> unit
2741 Suspend or restart reception or transmission of data on the given file
2743 descriptor, depending on the second argument: TCOOFF suspends output,
2744 TCOON restarts output, TCIOFF transmits a STOP character to suspend in‐
2745 put, and TCION transmits a START character to restart input.
2746 Raises Invalid_argument on Windows
2749 val setsid : unit -> int
2753 Put the calling process in a new session and detach it from its con‐
2755 trolling terminal.
2756 Raises Invalid_argument on Windows
2759OCamldoc 2022-07-22 UnixLabels(3)