Content-type: text/html Manpage of SAFE_PARSE_ID_LIST

SAFE_PARSE_ID_LIST

Section: (3)
Updated: 2011-07-26
Index Return to Main Contents

NAME

safe_parse_id_list, safe_parse_uid_list, safe_parse_gid_list - Parse a string for ids and store them in the safe_id_range_list

SYNOPSIS

#include safe_id_range_list.h

struct safe_id_range_list;
typedef struct safe_id_range_list safe_id_range_list;

int safe_parse_id_list(safe_id_range_list list, const char *value);
int safe_parse_uid_list(safe_id_range_list list, const char *value);
int safe_parse_gid_list(safe_id_range_list list, const char *value);

DESCRIPTION

These functions will add values to the list by parsing the value string. safe_parse_id_list only allows numeric values, while safe_parse_uid_list and safe_parse_gid_list allow non-numeric values that are converted to user and group ids respectively.

These functions differ from safe_strto_id_list(3), safe_strto_uid_list(3), and safe_strto_gid_list(3), by returning an error if non-whitespace exists in value after parsing as much as possible, i.e. the whole string must be a valid id range list.

Parameters

list: The safe_id_range_list to add values to. Must be non-NULL.
value: The range list string to parse. Must be non-NULL.

Range List Syntax

The syntax of a range list string is a set of ranges each separated by colons. Each range is either a single id, or a hyphen ('-') separated set of ids (the first must be less than or equal to the second and the second value may be a valid user or group name depending the function used. If a user or group name is used as the first part of a range the name must be separated from the hyphen by whitespace as a hyphen is a legitimate character in a name.

It is an error if the whole string to be parsed is not an id range list with optional whitespace at the end of the string. If it is not or another error occurs -1 is returned.

<RANGE_LIST>: := <RANGE>
:= <RANGE> <whitespace>* ':' <RANGE_LIST>
<RANGE>: := <ID>
:= <ID> '-' <ID>
:= <ID> '-' <whitespace>* '*'
<ID>: := <whitespace>* <number>
:= <whitespace>* <text_name>

Example Range Lists

3: Adds the value 3 to the list.
0:5:100-103: Adds the values 0, 5, 100, 101, 102, and 103 to the list.
root: user1 - user2 : 1000-*: When parsed with safe_parse_uid_list, adds the values 0, 500, 501 and 1000 and greater to the list assuming the user names root, user1 and user2 have the values 0, 500 and 501 respectively. The space after user1 is mandatory.

RETURN VALUE

The function returns 0 if no errors were encountered and only whitespace follows the parsed id range list. -1 is returned otherwise. errno is set to 0 on success and an appropriate value on error.

ERRORS

EINVAL: list or value was NULL. An invalid number or non-exist user or group name was encountered. The first element of a range was larger than the second. A value consisting entirely of whitespace was encountered. Or non-whitespace characters follow the parsed id range list.
ERANGE: A numeric value was encountered that was too large.
ENOMEM: A memory allocation failed.

AUTHOR

James A. Kupsch

Index

NAME

SYNOPSIS

DESCRIPTION

Parameters
Range List Syntax
Example Range Lists

This document was created by man2html, using the manual pages.
Time: 15:16:59 GMT, August 12, 2011